Cream of the Crop 11

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 11 / Cream of the Crop 11-2.iso / extra_2 / nadir11.zip / LANGREF.TXT < prev next >

Wrap

Text File | 1995-11-08 | 280KB | 7,739 lines

NADIR Version 1.0 LANGUAGE REFERENCE Enexe Systems PO Box 771 Ashgrove 4060 Qld Australia Copyright c 1994 by Enexe Systems. All rights are reserved. Licence Agreement Carefully read the following terms and conditions. If you do not agree, return the documents and unopened software for a refund. The commercial version of Nadir must be treated like a book. That is, one copy of the commercial version may be used by one person on one computer at a time. If it is moved to another computer for use by another person, it must be removed from the original computer. It may not be copied, except for taking backup copies for archive and security reasons. A runtime version of Nadir is provided with the commercial version. A system developed using the commercial version may be installed at a user site with the runtime version of Nadir. No royalty fees are required to install the runtime version at a user site. A product provided with the runtime version must be substantially different to the Nadir product. A product that provides front-ends or enhancements to Nadir may not be installed at a user site without written permission from Enexe Systems. The contents of any version of the product may not be modified in any way. While every effort has been made, and will be made to provide a quality product, Enexe Systems will not be liable for any problems caused by the use of the product. CONTENTS Null Value .............26 INTRODUCTION.................1 Boolean Value ..........26 Overview...................1 Variables ................26 Syntax Definitions.........3 Local Variables ........26 Command Line Definitions...3 Symbol Tables ..........27 General Comments...........3 Symbol Names ...........27 Subscripting ...........27 CHAPTER 1 LEXICAL ELEMENTS Collating Sequence .....28 .............................4 next, prev operators ...29 Whitespace.................4 Subscripting Symbol Table Comments...................4 Names ..................29 Names......................4 Subscripting Function Names Keywords...................4 .......................29 Operators..................5 Databases ..............30 String Constants...........6 Operand Conversion Rules .31 String Literals..........6 Arithmetic Operators ...31 Escape Sequences.........6 Comparison Operators ...32 Code Strings.............7 Numbers....................7 CHAPTER 4 EXPRESSIONS ...34 Operators ................34 CHAPTER 2 PROCESSING......8 >< Operator ............35 config.sys and autoexec.bat Operator Precedence ......35 .........................8 Expression Syntax ........35 Command Line Syntax........8 Primary Expression .......37 Command Line Switches....9 Lvalue .................38 Single User Processing..12 Symbol .................38 Processing the Input File.13 Function Call ..........39 Initialization..........13 argc ...................40 Processing..............14 next ...................40 Macro Arguments.........15 prev ...................41 Redefining Keywords.....16 Logical negation ! .....41 Macro Definition........16 Unary minus - ..........41 Expression Evaluation...17 Parenthesis ............41 Conditional Keywords....18 Multiplicative Expression 42 Expansion Rules.........19 Additive Expression ......42 Processing the Input File Relational Expression ....43 in a Macro..............20 Equality Expression ......44 Logical And Expression ...44 CHAPTER 3 LANGUAGE OVERVIEW Logical Or Expression ....44 ............................22 Conditional Expression ...45 Functions.................22 Assignment Expression ....45 Function Name...........22 Expression ...............46 Arguments...............22 Return Value............23 CHAPTER 5 STATEMENTS ....47 argv, argc..............23 Compound Statement .......48 Assigning Arguments.....23 Label Statement ..........48 Passing by value and by Null Statement ...........49 reference...............23 Expression Statement .....49 Variable Types............24 Return Statement .........49 String..................25 If Statement .............50 Integer.................25 While Statement ..........50 Float...................25 Do Statement .............50 Date....................25 For Statement ............51 i Switch, Case and Default System ...................76 Statements................51 SystemRestart ............76 Break Statement...........52 SysType ..................77 Continue Statement........52 TaskNum ..................77 Goto Statement............52 TimeNow ..................77 TokenNext ................77 CHAPTER 6 SYSTEM INTRINSIC TokenScanCreate ..........78 FUNCTIONS...................53 TokenScanDestroy .........79 Bunch.....................53 TokenTerm ................79 DateDay...................53 TokenType ................80 DateDayName...............53 TokenValue ...............80 DateMonth.................54 Unbunch ..................80 DateMonthEnd..............54 DateMonthName.............54 APPENDIX A SYSTEM DateMonthStart............54 PARAMETERS .................82 DateToday.................55 DateYear..................55 APPENDIX B SYSTEM LIMITS84 Dump......................55 Explode...................56 APPENDIX C SYMBOL TABLE Exit......................56 UTILITY - STU ..............88 FieldType.................57 Command Line Syntax ......88 FileClose.................57 STU Commands .............90 FileColumn................57 bstat - Brief Statistics90 FileDump..................57 check - Check Integrity 90 FileIndentSet.............58 copy - Copy Symbol Table92 FileLineGet...............58 dump - Dump Symbol Table92 FileOpen..................58 fstat - Full Statistics 92 FilePrint.................59 pack - Pack Symbol Table93 FileRemove................60 rbuild - Rebuild Symbol FloatToInt................60 Table ..................94 Level.....................60 rtest - Random Test ....94 LineCurr..................61 LineGet...................61 APPENDIX D ERROR MESSAGES96 LineNum...................63 cnd - Condition Handler ..96 OutputColumn..............63 fm - File Manager ........96 OutputIndentSet...........63 hm - Handle Manager ......96 PreProcessSet.............63 key - Key File Functions .97 Print.....................64 lex - Lexical Analysis ...97 Process...................65 mem - Memory Manager .....98 Signal....................66 mi - Macro Interpreter ...98 Spawn.....................66 mif - Macro Intrinsic SpawnRestart..............66 Functions ................99 StrCat....................67 mm - Macro Manager ......100 StrFromAscii..............67 mp - Macro Parsing ......102 StrFromLit................67 n - The main program ....106 StrFromQuoted.............68 st - Symbol Table .......107 StrLen....................69 vm - Virtual Memory .....107 StrMatch..................70 StrPos....................70 INDEX .....................109 StrSubs...................71 StrToAscii................71 StrToLit..................71 StrToLower................72 StrToUpper................72 SymClose..................72 SymCreate.................72 SymLock...................73 SymOpen...................74 SymRemove.................75 ii INTRODUCTION Overview Nadir is a programming language. It is designed to be simple yet intelligent, to reuse as many of its algorithms as possible to produce a small yet powerful programming system. It combines powerful macro generation capabilities, with the ability to write procedural functions. With it you can generate code for any language, analyse and manipulate text files, write database style applications that run unchanged under DOS and Windows, or even use it as a calculator. The name Nadir, the opposite of the zenith, is used to signify a starting point, a small set of rules and functions upon which things can be built. Enexe Systems has developed a product that will appeal to students, professional programmers, and the home enthusiast who wants a no frills programming system with a minimum of fuss and mumbo jumbo that is easy to learn because it is based on the syntax of C. The base nucleus of Nadir comprises a number of modules that perform language parsing, language interpretation, error handling, and a set of inbuilt intrinsic functions for performing string, numeric and date maniplation, and the control of data files and the symbols in them. The nucleus is written in C, and has been ported to run under DOS and Windows. Other modules of intrinsic functions have been written to perform Screen Dialogues and Report Formatting. These functions have been written to perform under DOS in text mode and Windows. When an application is written using these functions, it will work under DOS and Windows without change. A Developer's Kit is planned to allow users to add modules of intrinsic functions written in C. Object modules of the nucleus will be provided, and customized versions of the Nadir programs can then be linked. Introduction 1 Nadir is designed to work with fields. Being an interpreted language, it is slow when compared with programs written in C. For writing applications, complex algorithms should be developed using C and made available by adding these algorithms to the language as intrinsic functions. The Nadir code should be the 90% of the code that runs for 10% of the time. 2 Nadir Reference Manual Syntax Definitions Syntax definitions consist of the entity being defined followed by a colon. Alternatives follow on separate lines. Optional elements are shown inside angle brackets Example macro-arg-list: ( macro-argument-list ) macro-argument-list: macro-argument macro-argument-list, macro-argument macro-argument: user-defined-word < macro-arg-list > token macro-argument terminator token A macro-arg-list is a left parenthesis, followed by an macro-argument-list, followed by a right parenthesis. A macro-argument-list is a macro-argument or a macro-argument-list followed by a comma and a macro-argument. A macro-argument is either a user-defined-word, followed by an optional macro-arg-list, or a token, or a macro-argument followed by a terminator and a token. Command Line Definitions When the syntax of commands are shown, brackets, [], are used to show optional items. Example stu command [switches] [file1 [file2]] The user must specify the command word, the switches, file1 and file2 are optional. General Comments All the examples show the date in the dd/mm/yyyy format. There is a system parameter that allows the output format of the date to be modified. Introduction 3 CHAPTER 1 LEXICAL ELEMENTS This chapter provides a formal definition of the Nadir lexical elements. When an input file is read, it is broken into components known as lexical elements or tokens. The syntax of the Nadir language, or the legal combination of tokens is dealt with in the following chapters. In Nadir, case is significant. i.e. The name MyMacro is considered to be a different name to mymacro. Whitespace Whitespace is used to separate tokens in the input file. The whitespace characters are space, tab, carriage return, newline, vertical tab and formfeed. Any amount of whitespace may be used to separate the tokens in the input file. Comments Comments may be used to write notes in the program source. The contents of the comment text are ignored. Comments may be defined in two ways. /* .... */ The character pair /* begins the comment. The comment ends with the next occurence of the character pair */. // ..... The character pair // begins the comment. The comment ends with the next newline character. Names A name starts with an alphabetic character or the underscore character, and may contain any number of alphanumeric or underscore characters. The name ends when a character that is not an alphanumeric or an underscore is encountered. Keywords Keywords are special forms of a name. 4 Nadir Reference Manual The following words have special meaning when processing the input file. Define Eval If Elseif Else Endif The following words are reserved words when defining macros. These words may not be used as variable names or components in variable names. if else return do while for switch goto break continue argv argc next prev Operators Operators are sequences of non alphabetic characters. The following table gives each operator and a short description of their use. Later chapters describe the operators in more detail. Operat Description and use or { Begin compound statement } End compound statement ( Argument list definition, set expression precedence ) [ Begin subscript ] End Subscript , Argument separator >< Argument separator ; Statement terminator + Addition - Subtraction, unary minus . Concatenation * Multiplication / Division % Modulus (remainder) ? Conditional operator : Conditional operator = Assignment operator += Assign sum -= Assign difference *= Assign product /= Assign quotient %= Assign modulus .= Assign concatenation == Logical equal to ! Logical not != Logical not equal to < Logcal less than <= Logical less than or equal to > Logical greater than Chapter 1 Lexical Elements 5 >= Logical greater than or equal to && Logical and || Logical or ^ Variable component seperator String Constants There are two types of string constants, string literals and code strings. String Literals String literals begin and end with matching single or double quotes. In Nadir, the use of single and double quotes is interchangeable. Stings may be continued onto the next line by using the backslash newline combination at the end of the first line. Example "abcd" 'abcd' "ab\ cd" all specify strings containing 4 characters, abcd. Escape Sequences Escape sequences are necessary to allow the definition of non printable characters in a string literal. They also allow the definition of double quotes in a string literal that begins and ends with double quotes. The valid escape sequences are shown in the following table. Sequen Char Remarks ce \a BEL Audible bell \b BS Backspace \f FF Formfeed \n LF Linefeed \r CR Carriage return \t HT Horizontal tab \v VT Vertical tab \\ \ Backslash \' ' Single quote \" " Double quote \xhh hh, a string of up to 2 hex digits \Xhh hh, up to 2 hex digits 6 Nadir Reference Manual \ooo ooo, up to 3 octal digits Notes If a character that follows a backslash is not in the list above, it is taken to mean the character itself. eg \z is lowercase z, \? is question mark. The hex string after \x or \X ends with the first non hexadecimal character. eg "\x7g" is two characters, a character with a value of 7, followed by lowercase g. If a digit between 0 and 7 follows the backslash, it is assumed to start an octal string. The octal string ends with the first non octal character, or an octal character that would make the character value more that octal 377. eg \777 is taken to mean 2 characters, one with an octal value of 77, followed by the character 7. Code Strings Code strings start and end with a matching accent ` character. Each character in the input file is placed in the code string. There are no escape sequences and it is not possible to have an accent in a code string. Example `abc def` "abc\ndef" are equivalent. Both specify strings of 7 characters, abc newline def. Numbers There are two types of numeric tokens, integer and floating point. Integers contain decimal digits. eg 1234 All integers are stored internally as 32 bit signed integers. Floating point numbers contain a decimal point. The integer before the decimal point and the fraction part after the decimal point must either be specified. eg .2, 22. and 22.22 are valid floating point numbers. A dot on its own is not seen as a floating point constant of zero. Floating point numbers are stored internally as double precision floating point numbers. Chapter 1 Lexical Elements 7 CHAPTER 2 PROCESSING The Nadir program is a filter. It takes input from an input file and writes output to an output file. This chapter describes the command line syntax and the method Nadir uses to process the input file to produce the output file. The runtime version of Nadir does not allow the processing of an input file. Applications may be executed using the runtime version using the -e or -p command line switches. There are two versions of the Nadir program. n.exe is the version that runs in text mode under DOS. nw.exe and nsys.dll are the files that run under Windows. config.sys and autoexec.bat The FILES statement in config.sys must allow for the number of files that are to be opened. This figure has to allow for all the files that are opened at one time by all active Windows tasks. If files are to be shared, the DOS SHARE program has to be loaded. This can be done in config.sys using the INSTALL statement, or by running the program directly in autoexec.bat. The /f and /l switches may be specified to manage the number of files that are to be shared. See the Nadir -s switch and the section Single User Processing later in this chapter. The following statement in config.sys will load the share program, allocate 3072 bytes for storing file sharing information and specifies that 64 files can be locked at one time. INSTALL C:\DOS\SHARE.EXE /F:3072 /L:64 Command Line Syntax DOS Command n [switches] [<infile] [>outfile] [infile] Windows Command nw [switches] [infile] 8 Nadir Reference Manual Under DOS the default input file is standard input and the default output file is standard output. They may be redefined by using the > and < redirection operators, or the -i and -o command line switches. Windows Windows does not provide standard input or Input/Output standard output or the < and > redirection operators when processing a command. To specify input, use the -i switch or specify an infile on the command line. If -i is not specified, the first time data is requested from the input file, end of file is returned. If -o is not specified, all output is collected in a temporary file and presented to the user using the browser. See Appendix A, System Parameters for details specifying a browser. Command Line Switches Switches may be specified by either a minus sign or a slash. Spaces may be optionally present between the switch name and the switch value. If a switch is specified more than once the last value will be used. If the -i switch is used and the infile argument is also specified, the last one specified will be used. Switch Description -a<name> After processing, the macro specified by name is executed. -b<name> Before processing is performed, the macro specified by name is executed. The macro is executed once. If an error is signalled and the -c switch is active, it will not be re-executed. The same comment applies to the -a switch. -c Cycle on errors If an error is signalled and the -c switch is active, Nadir will release all resources such as memory and file handles and restart the program. If the switch is not specified, the program terminates when an error is signalled. In this case, the return code of the Nadir program will be 20. Chapter 2 Processing 9 -e<name> Execute Macro. The macro specified by name is executed. The input file is not processed. This is similar to -p, but is more efficient because the memory used by the macro compiler is not allocated Data may be read from the input file using system intrinsic functions. Any return value from the macro is discarded. -i<name> Input filename. name specifies the input filename. Under DOS, if -i is not specified, input is read from standard input. Under Windows, if -i is not specified, any attempt to read from the input file will immediately return end of file. Under Windows, if -i is not specified, -e or -p must be specified for Nadir to perform a task. -l Use macro library. If specified, Nadir will open the default macro library, mlib.dat, on startup. Any reference to a user written macro, or symbol that is not found in the mdat symbol table, is searched for in the macro library. If the -L switch is used, -l is assumed. If -l, or -L is not used, Nadir will not open a library. - No Keywords. n[flags] This is used to pre-process Nadir code. It allows the user to ignore some or all keywords in the input file. Keywords are If, Else, Elseif, Endif, Eval and Define. flags is optional and is a string that may contain :- d - Ignore Define keyword e - Ignore Eval i - Ignore If, Elseif, Else and Endif If flags is not specified, dei is assumed. 10 Nadir Reference Manual -o<name> Output filename. name specifies the output filename. Under DOS, if the -o switch is not specified, output is written to standard output. Under Windows, name is optional. If specified, output is directed to a file with that name. If -o is specified without name, output is written to a temporary file and is shown using the browser program after the Nadir program finishes processing. If -o is not specified under Windows, all output is discarded. - Process String p<string The string is processed as if it > occurred in the input file. Processing is complete when data from the string is exhausted. Data may be read from the input file using system intrinsic functions. -r Reset input on errors. If the program cycles after an error, this switch will cause Nadir to start processing at the start of the input file. -s Single User Mode When specified, files are not opened shared, no locking is performed, and the special single user processing on incorrectly opened files is performed. -D<dir> Default Data Directory If a full pathname is not specified when a symbol table is opened, Nadir uses the dir value to specify the directory. If not specified, files will be opened in the default directory. -L<name> Library data symbol table filename. name specifies the filename of a macro library symbol table. This file contains compiled definitions of macros. -M<name> Macro data symbol table filename. name specifies the filename of the macro data symbol table. This data file contains the compiled definitions of macros. Chapter 2 Processing 11 -P<name> Parameters symbol table filename. name specifies the filename of the symbol table containing system parameters. - Size of local value stack. Sl<size> Local variables may be defined in macros. Their values are kept on the local value stack. size specifies the size in bytes of the local value stack. If not specified, size defaults to 4096 bytes. - Memory Block Size. Sm<size> This applies to the Windows version only. Dynamic memory is obtained from the operating system in chunks of size bytes. Nadir then manages these chunks to provide dynamic memory allocation. If memory is required, and there is not enough free memory in the chunks that have been obtained, Nadir will request another block from the Operating System. If -Sm switch is not used, memory block size defaults to 40960 bytes. - Size of operand stack. So<size> The operand stack is used to hold values when expressions are evaluated when executing compiled macro code. size specifies the size in bytes of the operand stack. If not specified, size defaults to 4096 bytes. -T<dir> Temporary File Directory dir specifies the directory where temporary files are created. All temporary files created by Nadir have a "$$$" extension. If not specified, temporary files are created in the default directory. -U<name> Universal symbol table filename. name specifies the filename of the universal symbol table. Universal symbols are permanent and may be kept after invokations of Nadir. Single User Processing When the single user switch -s is specified, no file sharing is possible. The DOS SHARE program does not have to be loaded. If the -s switch is not specified, the SHARE program must be loaded before running Nadir. 12 Nadir Reference Manual When using single user mode, a check is made when each file is opened as to whether it was properly closed. If it was not properly closed, the open routine calls a user written function called SysFileRecover with one argument, the name of the file. This function can allow the user to check or restore the file. If this program uses the check option of the symbol table utility, stu, and the file has no errors, the utility will reset the improperly open flag in the file. If the SysFileRecover function does not exist, the program will be exited with a message "Symbol Table blah not properly closed". Processing the Input File Initialization When Nadir is started, default symbol tables are opened. Symbol tables are used to store the values of symbols. Symbols are variables and may be manipulated when macros are executed. Symbols are referenced in the macro language by using a prefix like univ, glob, parm, and mdat. The symbol tables that are always opened are described below. Intrinsic functions allow access to other symbol tables. univ The universal table is a permanent symbol table. Permanent symbol tables may be used to store data from one invokation of Nadir and refer to it by a later invokation. The universal table may also be shared. A shared table may be opened by simultaneous invokations of Nadir, either in different tasks under Windows, on different DOS boxes under Windows, or on different machines on a network. glob The global table is temporary. On each invokation, a table is created, and deleted when Nadir exits. Unlike univ, global data cannot be shared between sessions running simultaneously. Each invokation of Nadir will have a separate global symbol table. mdat The macro data file is a permanent table that may be shared. This file contains the compiled macro definitions. When macros are defined using the Define word, the code is analysed syntactically, converted to an internal form and stored in symbols in the mdat file. When a macro is evaluated, the internal form is interpreted to execute the statements in the macro. Chapter 2 Processing 13 mdat is not limited to storing compiled macro code and may also contain any symbols that the user chooses to store. parm The parameter file is a permanent file that may be shared. Its purpose is to contain system and user defined parameters. System parameters are used to alter the behaviour of Nadir, and are read from the parm file during initialization. See an appendix for details. mlib The macro library, mlib, is opened only if the -l or -L startup parameters are specified. Any reference to a macro definition or a symbol in mdat that is not found is attemped in mlib. Processing The input file is lexically analysed. If a token is not a name, the token is written to the output file. The whitespace before the token is also output. See Chapter 1 for information on Lexical Analysis. There are six words that are reserved and have special meaning when Nadir processes the input file. They are If, Elseif, Else, Endif, Eval and Define. The behaviour of these words in the input file is described below. If a name is not one of the reserved words, mdat and optionally mlib are checked to see if the word is a user-defined macro. If the name is not user defined, it is output to the output file, and the processing of the input file continues. If there are no user defined words and no reserved words in the input file, the output file will be the same as the input file. If the name is user defined, the value of the macro with that name is output. Nadir first searches the mdat file for the word. If the word is not found, and the -l ot -L command line switch has been used, Nadir will then search the macro library, mlib. If a macro is found it is executed and the value returned by the macro is output. Macros are defined by using the Define keyword. If an argument list exists after the name of the macro in the input file, the value returned by the macro replaces the macro name and the argument list in the input file. Argument lists are described in more detail in a later section. 14 Nadir Reference Manual Macros, when executed may perform the Print intrinsic function. The output of the Print function is put in the output file before the return value of the macro is output. Macro Arguments Arguments may be optionally passed to a macro when a user defined word in the input file is the name of a macro. The syntax of an argument list is :- macro-arg-list: ( macro-argument-list ) macro-argument-list: macro-argument macro-argument-list, macro-argument macro-argument: user-defined-word < macro-arg-list > token macro-argument terminator token If a user defined word is encountered, the return value of the macro replaces the text in the input file. Arguments to macros that are invoked during processing are always passed as strings, exactly as they appear in the input file. Arguments are separated by commas, and if more than one word appears before the next comma, the words and the intervening whitespace, the terminators, are concatenated into one string. Example String in input file Remarks MacroName(abcd) Macro called with a string of four characters, abcd. MacroName(abcd, efgh) Called with 2 arguments 4 character string abcd 4 character string efgh. MacroName(abcd efgh, Called with 2 arguments 1234 5678) 9 character string abcd efgh 9 character string 1234 5678 MacroName("abcd\nefgh") Called with 1 argument 12 character string, which includes the double quotes, and a backslash. Chapter 2 Processing 15 MacroName("abcd\ Called with 1 argument efgh") 12 character string, which includes the double quotes, a backslash and a newline. Redefining Keywords Keywords have special meaning when processing input. The keywords are Define, Eval, If, Elseif, Else and Endif. The values of the words may be changed by setting system parameters in the parm symbol table. i.e. symbol parm^system^word^Define may be used to redefine the word Define to for example DEFINE_A_MACRO. See Appendix A for more information on these System Parameters. Macro Definition Define The Define keyword is used to define or create a macro. If a macro exists, it is overwritten with the new definition. When macros are defined, the macro text is compiled into an internal form that is used when the macro is executed. This internal form is stored in symbols in the mdat symbol table. The syntax of the Define statement is :- Define macro-name <(<arg-name-list>)> compound- statement macro-name: name macro-name ^ <name> arg-name-list: name arg-name-list , name The macro name may contain carets. If a caret is not present, the macro is saved in the mdat symbol table. If a caret is present, the name component before the first caret specifies the symbol table where the macro is saved. The name of the macro in the symbol table is the macro- name with the first name component and the first caret removed. The optional arg-name-list allows the definition of argument names that are used in the body of the macro to refer to the arguments passed to the macro. The arg-list can be empty, or can have any number names, separated by commas. 16 Nadir Reference Manual The compound statement defines the processing that is performed when the macro is invoked. The syntax of a compound statement is defined in a later section. Briefly, it is a series of statements enclosed in matching braces {}. If a return statement is processed, the value returned by the macro is the value of the expression after the return keyword. If the compound statement does not have a return statement, the null value is returned. Example The following example shows the definition of a macro that takes 2 arguments, and some invokations of it. Define Adder(a1, a2) { return a1 + a2; } 3 + 2 is Adder(3,2) 3 + nothing is Adder(3) or Adder (3,) When this is processed, the following output is produced. 3 + 2 is 5 3 + nothing is 3 or 3 Expression Evaluation Eval Eval is used to evaluate expressions when processing input. The syntax of the Eval statement may be one of two forms. Eval ( expression ) Eval compound-statement The text of the Eval statement is replaced by its evaluation. When parenthesis are used, the expression is evaluated, and its value output. The closing right parenthesis is not required if the expression occurs at the end of the input. In the second case, the compound statement is evaluated as if it was a macro. The return statement is used to set a return value. If a return statement is not processed, the null value is returned. In either case, the text of the expression or the compound statement is compiled into the internal form using the macro language syntax rules, and then evaluated. Examples When the following text is processed Chapter 2 Processing 17 Today, Eval(DateToday()) is Eval { dayName = DateDayName(DateToday()); if (dayName == "Saturday" || dayName == "Sunday") return "on the weekend"; else return "a week day"; } The following text is output, (if you run it on 24/11/1993) Today, 24/11/1993 is a week day Conditional Keywords The words If, Elseif, Else and Endif may be used to conditionally process blocks of text in the input file. For each If, there may be any number of Elseif keywords and there must be a matching Else or Endif. For every Else, there must be a matching Endif. The keywords may be used as follows If ( expression-1 ) <section-1> <Elseif ( expression-2 ) section-2> .... <Elseif ( expression-n ) section-n> <Else else-section> <Endif> If expression-1 evaluates to true, the text represented by section-1 is processed. Otherwise, if expression-1 evaluates to false, section-1 is ignored (not processed). When an expression is evaluated, it is evaluated using the macro language rules of syntax and execution. In effect, the expression is compiled like a macro, and then executed. This, and the values of true and false expressions are defined in a later section. In the true case, after section-1 has been preprocessed, control passes to the matching Endif. When expression-1 is false, control passes to the next Elseif directive, where expression-2 is evaluated. If expression-2 evaluates to true, section-2 is processed and control passes to the matching Endif. Otherwise if expression-2 is false, control passes to the next Elseif, and so on, until either Else or Endif is encountered. The optional else-section is processed when no other section has been processed. The else-section ends with the matching Endif. 18 Nadir Reference Manual The If, Elseif, Else, Endif structure may be nested. Expansion Rules When expanding, comments are retained and written to the output file wherever possible. The comment after a user defined word is not output, as Nadir ignores comments when it looks for the next token to see if an argument list exists. This behaviour occurs because the program can then easily deal with comments of any length. For Define, If, Elseif, Else and Endif, the directive itself expands to nothing. Any whitespace before the keyword, back to, but not including the most recent newline, is ignored. Any whitespace and comments after the required syntax for the keyword, up to and including the first newline is dropped. The intention is to drop complete lines that contain these directives. When Eval and user defined words are expanded, the words and the necessary syntax that goes with them are replaced exactly by the value of the expansion. The whitespace before and after is output exactly as in the input file. Example The following input, when processed aaa Define Test1() { Print(".Test1."); } bbb Define Test2() { Print(".Test2."); } cccc Test1 dddd /* comment */ Test2 /* another comment */ ( ignored arg) eeee If (1) ffff Else gggg Endif hhhh If (1) /* comment about If directive */ /* comment about output text */ this is output text Else /* comment on Else directive */ no possibility here Endif /* comment of Endif directive */ blah Eval(33+44) blah Eval { tmp1 = "24/11/1993" - "20/09/1953"; return tmp1; } blah will produce the following output aaabbb cccc .Test1. dddd /* comment */ .Test2. eeee ffffhhhh /* comment about output text */ this is output text blah 77 blah 14675 blah Chapter 2 Processing 19 Processing the Input File in a Macro The input file may be processed from within a macro, either by processing tokens using the Token intrinsic functions, or using the LineCurr and LineGet functions to process by each line. When performing lexical analysis, there is a concept of the current token. The whitespace before the current token is known as the current terminator. When a macro is invoked without an argument list, the current token is the token after the macro name in the input file. If the user performs TokenNext or LineGet functions within the macro, Nadir will continue processing at the current token. If an argument list is present, the current token will be the closing right parenthesis of the argument list. After invoking the macro, Nadir performs automatically performs a TokenNext to move to the next token. It does this to retain as many comments in the output file as possible. This behaviour needs to be considered if TokenNext or LineGet functions are called in a macro that has an argument list. 20 Nadir Reference Manual Example The following file, when processed, Define TestToken() /* designed to test TokenValue, TokenNext and TokenType reads tokens from input file until a non integer is found, or the word TestTokenEnd. Returns the total of all the integers found. */ { while (TokenType() == "INT") { total += TokenValue(); TokenNext(); } if (TokenType() == "NAME" && TokenValue() == "TestTokenEnd") TokenNext(); return total; } TestToken 1 2 3 qwerty TestToken 1 2 3 4 TestTokenEnd 5 6 TestToken 1 2 3 4 5 EndOfFile will produce the following output. 6 qwerty 10 5 6 15 EndOfFile Chapter 2 Processing 21 CHAPTER 3 LANGUAGE OVERVIEW This chapter introduces the language. User written functions are defined using the Define keyword in the input file. The term macro is another name for a user written function. When the input file is processed, the macro source code is converted to an internal form, and stored in symbols in the mdat symbol table. Execution time is when an interpreter reads the internal form and uses this to perform the processing specified by the macro's statements. Functions There are two types of functions, user written and intrinsic. User written functions, or macros, are written using the Define keyword in the Nadir input file. Intrinsic functions are written in C and are part of the Nadir executable program. Intrinsic functions may be written and added to an executable program using the Developer's Kit. Function Name The function name may contain carets. When a function name does not contain a caret, Nadir searches for an intrinsic function and then for a user written function in mdat. If it is not found, and a macro library was specified on the command line, mlib is searched. If a caret is present, the name component before the first caret specifies the symbol table where the function is read from. The name of the function in the symbol table is the function name with the symbol table name and the first caret removed. Arguments Using Define, a list of arguments can be specified. The arguments in the function can then be referenced by name. The name given to an argument has to be a valid lexical name. A valid name starts with an alphabetic character or the underscore character, and may contain any number of alphanumeric or underscore characters. 22 Nadir Reference Manual If a function is called, and an argument is not passed, the argument value in the function will be the null value. Return Value A function always returns a result. The return statement can be used to specify the return value of a function. If a return statement if not executed, the null value will be returned. Example The following function returns the arithmetic sum of up to 8 arguments. Define AddArgs(a, b, c, d, e, f, g, h) { return a + b + c + d + e + f + g + h; } argv, argc Arguments passed to a function can be accessed using the argv and argc special variables. Example The following function returns the arithmetic sum of all the arguments. Define AddArgs() { for (i = 0; i < argc; i +=1) rv += argv[i]; return rv; } Assigning Arguments Inside the function, arguments may be assigned. Example Define Test(table) { if (!table) // if value of table not passed table = "univ"; // default to univ . . . } Passing by value and by reference By default, arguments are passed by value. In this case, if an argument is modified in a function, it is modified in the called function and not modified in the calling function. Chapter 3 Language Overview 23 Arguments may be passed by reference using the & operator in the calling function. Any local variable, argument or symbol may be passed by reference. In this case the value is modified in the calling function. Example The following input, when processed, Define Called(a, b) { Print(a, " ", b, " before change in called func\n"); a = 55; b *= 2; Print(a, " ", b, " after change in called func\n"); } Eval { a = 12; b = 24; Print("Values of a and b\n"); Print(a, " ", b, " before func call\n"); Called(a, &b); // a passed by value // b passed by reference Print(a, " ", b, " after func call\n"); } will produce the following output. Values of a and b 12 24 before func call 12 24 before change in called func 55 48 after change in called func 12 48 after func call Variable Types There are no declaration statements to define the type of variable in Nadir. The contents of the field determines the type of a variable. When an operation is to be performed, Nadir examines the contents of the operands, performs any necessary conversions, and then produces a result. The different types of variable that Nadir recognizes are string, integer, float and date. 24 Nadir Reference Manual Examples In the expression "1234" + "1234.5678", the operands are strings, the operator +, or arithmetic addition. Since the operands are strings, Nadir sees if they contain an integer, float or date. In this case the operands are recognized as an integer and a float. Nadir will convert the integer to a float, perform the addition, and produce a float result. Nadir will hold the result as a float, so that if further arithmetic is performed, no conversions may be necessary. If the result was printed using the Print intrinsic function, the float would be internally converted to a string prior to printing. Expression Result "" + 4 4 (nothing plus 4) "jhgjkhg" + 4 4 (same, nothing plus 4) "123" + 12 135 "12.2" + 15 27.2 "14/2/1983" + 5 "19/2/1983" "19/2/1983" - 5 "14/2/1983" String Strings contain sequences of characters. Integer Integers are stored internally as signed 32 bit integers. A valid integer has an optional negative sign and followed by one or more digits. Float Floats are stored internally as 8 byte double precision floating point values. This allows for 14 digits of accuracy. A valid float has an optional negative sign followed by one or more digits with one decimal point. Date Dates are stored internally as a 32 bit integer as a number of days from a starting date. The date format may be Australian, dd/mm/yyyy, or US, mm/dd/yyyy. A symbol in parm, parm^system^date^format specifies the date format on startup. If "u" (the character u), the date format is US, otherwise it is Australian. Chapter 3 Language Overview 25 Null Value The null value is a zero length string. It is used to signify nothing, and is the value returned when a variable or symbol has not been set. Setting a symbol to the null value using an assignment operator will delete it from the symbol table. Boolean Value Boolean values are produced by the logical operators. These include < <= > >= == != && and ||. Values need to be converted to boolean values when processing if statements, evaluating &&, || and ?: operators, and where intrinsic functions specify an argument to be a boolean. A boolean value is stored internally as an integer, zero is false, a non-zero integer is true. Zero length strings, or null values have a value of false. Strings that have one or more characters have a boolean value of true. Numeric values, integers, floats, and the internal representation of dates are false if they are zero, otherwise they are true. Variables In Nadir, values may be stored in function arguments, local variables or in symbol tables. When a function argument, local variable or symbol that does not exist or has not been defined, is referenced, the null value is returned. Local Variables Local variables are used in functions. They are only visible within the function that they are used. They may only be modified outside the function that they are defined in by passing the variable by reference to another function. Local variables are defined when they are first referenced. Local variables are always initialized to the null value. 26 Nadir Reference Manual The name given to a local variable has to be a valid lexical name. A valid name starts with an alphabetic character of the underscore character, and may contain any number of alphanumeric or underscore characters. Symbol Tables Symbol tables contain symbol names and symbol values. There are a number of system defined symbol tables, univ, glob, parm, mdat, mlib, data, temp. The user may define other symbol tables using the Sym family of intrinsic functions. Symbol tables may be permanent, shared, or temporary. Symbols are stored in a symbol table in alphabetic order by name. The next and prev operators may be used to scan through symbol tables. Symbol Names Symbol names are a series of lexical names with caret ^ separators. The first component specifies the name of the symbol table. univ^name^sex^m glob^total^group^Qld A symbol value is created or modified with an assignment statement. univ^name^sex^m = "Male"; univ^name^sex^f = "Female"; glob^total^group^Qld = 0; To delete a symbol, set it to the null string. univ^firstpass = ""; Subscripting Symbols may be subscripted by specifying a subscript expression in square brackets [ and ]. At runtime, the expression is evaluated and the name of the symbol is formed by concatenating the components. Chapter 3 Language Overview 27 Example The following input, when processed, Eval { univ^sex^m = "male"; univ^pers^bloggs^sex = "m"; univ^pers^bloggs^name = "Joe Bloggs"; code = "bloggs"; Print(univ^pers^[code]^name, " is ", univ^sex^[univ^pers^[code]^sex], "\n"); } will produce the following output. Joe Bloggs is male By using subscripts, it is possible to create a symbol name containing components that are not names, but integers, floats and date types. Example Source Code Remarks univ^10^code Invalid syntax, one of the components is not a name univ^[10]^code Valid syntax, resulting symbol name is univ^10^code Collating Sequence Symbol names are stored in symbol tables in the collating sequence order. This order is determined by comparing the symbol names. Each component of the name, the parts separated by carets, are compared in turn from left to right. The comparison of each component uses the rules for Comparison Operators, as defined in the Operand Conversion rules section. When a component is less than the other, the name that it belongs to is before the other in the collating sequence. Example Name 20^xyz is before 100^abc because the first components are both integers, and 20 is numerically less than 100. Name 100a^bc is before 20^xyz. The first components are different types, 100a being a string (100a is not a valid integer), and 20, an integer. When a string is compared to an integer, the integer is converted to a string, and a string comparison is performed. 28 Nadir Reference Manual next, prev operators The following code uses the next operator to print all symbols in the univ table. The next operator returns the next name after a symbol. The name is returned without the table name. The prev operator will return the symbol name before a symbol. If there is no next or previous value, the null value is returned. name = ""; while (name = next(univ^[name])) Print(name, " \t= ", univ^[name], "\n"); Subscripting Symbol Table Names The symbol table name may be subscripted. The following example shows a function that will list all symbols in the symbol table specified by the "table" argument. When the example is processed, the contents of the univ table will be output. Define List(table) { while (name = next([table]^[name])) Print(name, " \t= ", [table]^[name], "\n"); } List(univ) Subscripting Function Names Function names can be subscripted. The following example shows how the action from a menu selection may be used to branch to the required function. Eval { pre = "mdat^menu^main"; [pre]^u = "SysUtilities"; [pre]^r = "SysReporting"; [pre]^i = "InvoiceEntry"; [pre]^c = "ClientMtce"; [pre]^e = "SysEnquiry"; } Define HighLevelFunction() { . /* following code will call function based on contents of userChoice. System will error if userChoice does not contain "u", "r", "i", "c", or "e" */ [mdat^menu^main^[userChoice]](); . } Chapter 3 Language Overview 29 Databases Databases can be kept using the symbol tables. Building a database becomes a task of choosing an appropriate naming convention. Consider a database of person facts. For this example it is proposed that the code is a system generated number. The dots represent repeated leading parts of the symbol names. person^[code]^gnam = given name ..............snam = surname ..............dob = date of birth ..............sex = either "m" or "f" Sample data for this example could be :- person^[1]^dob = "15/8/1963"; ...........gnam = "Mary"; ...........sex = "f"; ...........snam = "Smith"; .......[2]^dob = "12/2/1954"; ...........gnam = "Frederick"; ...........sex = "m"; ...........snam = "Johnson"; .......[18]^dob = "1/12/1968"; ............gnam = "Bruce"; ............sex = "m"; ............snam = "Smith"; These symbols are examples of one to one relationships, where one person can only have one date of birth. To build keys, we build symbols names and set their values to "y" to indicate their existence. The following names and examples are for access by surname, sex and date of birth. These are one to many relationships, where any number of people could have the same surname. dob^person^[dob]^[code] = "y"; sex^person^[sex]^[code] = "y"; surname^person^[snam]^[code] = "y"; Sample values for the above names could be :- dob^person^["12/2/1954"]^[2] = "y"; // Johnson ...........["15/8/1963"]^[1] = "y"; // Smith, Mary ...........["1/12/1968"]^[18] = "y"; // Smith, Bruce sex^person^["f"]^[1] = "y"; // Smith, Mary ...........["m"]^[2] = "y"; // Johnson .................[18] = "y"; // Smith, Bruce surname^person^["Johnson"]^[2] = "y"; ...............["Smith"]^[1] = "y"; // Mary .........................[18] = "y"; // Bruce 30 Nadir Reference Manual The method chosen to store the symbol names and values uses a b-tree with leading key compression and allows for variable length values. By using leading key compression, the repeated parts at the beginning of the symbol name are not stored. This is represented by the dots in the examples above. This behaviour will determine the efficiency of the symbol naming convention chosen. The other consideration is that symbols next to each other in the collating sequence will tend to be stored in the same disk block. In the above example all the information for Mary Smith will most likely be in the same disk block. Operand Conversion Rules Arithmetic Operators The following table shows the results of an arithmetic operation between two operands. The arithmetic operators are + - / * and %. The divide function returns zero if the divisor is zero. The table shows the type of result and any conversion that is automatically performed when the expression a op b, eg a + b, is evaluated. String b Integer Date b Float b b String a Integer Integer Date * Float * * * Integer a Integer Integer Date Float ** * Date a Date * Date Integer Date *** Float a Float * Float ** Date *** Float * String is converted to zero ** Integer automatically converted to float. ***Float automatically converted to integer. For dates, the internal value, a 32 bit integer which represents a number of days from a starting date, is used in the arithmetic operation. Chapter 3 Language Overview 31 The intention with dates is to perform date arithmetic. If you subtract 2 dates, the result is an integer, the number of days between the dates. Adding an integer, a number of days, to a date produces a date. Comparison Operators When relational, equality and logical operators are performed, a boolean value always results. These operators are <, <=, >, >=, == and !=. The type of comparison performed varies depending on the operands. Numerically, 2 is less than 100, however "2" is greater than "100" if a string comparison is performed. A string comparison is performed by comparing the ascii values of each character in the strings, in turn from left to right. If one string is shorter than the other, and the leading characters are the same, the shorter string is less than the longer string. Integers and floats are compared using their numeric values. For dates, the internal value, a 32 bit integer which represents a number of days from a starting date, is used in the comparison operation. If a date is less than another date, it is an earlier date. The table shows the type of comparison performed and any conversion that is automatically performed when the expression a op b, eg a < b is evaluated. String b Integer Date b Float b b String a String String * String * String * Integer a String * Integer Integer Float ** Date a String * Integer Integer Float ** Float a String * Float ** Float ** Float * Non string value converted to string ** Integer or date is converted to a float. Example If a string is compared to a float, the float is converted to a string, and a string comparison is performed. 32 Nadir Reference Manual If a float is compared to an integer, the integer is converted to a float, and a float comparison is performed. Chapter 3 Language Overview 33 CHAPTER 4 EXPRESSIONS An expression is a sequence of operators and operands that performs a calculation. The precedence of the operators specify the order of evaluation. During evaluation, Nadir may automatically perform conversions. Operators The following operators are available in expressions. Operator [] Array subscript () Function call, Evaluate expression ! Logical negation (not) - Unary minus & Pass by reference next Next symbol in table prev Previous symbol in table * Multiply / Divide % Modulus (remainder) + Plus (addition) - Minus (subtraction) . Concatenation < Less than <= Less than or equal to > Greater than >= Greater than or equal to == Equal to != Not equal to && Logical AND || Logical OR ?: Conditional = Assign *= Assign product /= Assign quotent %= Assign modulus += Assign sum -= Assign difference .= Assign concatenation , Comma >< Alternative comma 34 Nadir Reference Manual >< Operator >< is an alternative to the comma. It is treated internally as a comma. The following shows an example of its use. The intention is to highlight, where the use of a comma may confuse. Define DosCharFieldDefine(title, name, row, value) { Print( ` `><name><`ch = parm^screen^char^`><value><`; SdPrompt(scr, `><row><`, 7, "`><title><`"); SdPrompt(scr, `><row><`,23, ":"); SdCombo(scr, "`><name><`ch", 1, `><row><`, 25, 6, 20, &`><name><`ch, "temp^ch^"); `); } Operator Precedence The following table shows the precedence of the operators, from the highest first to the lowest. () [] ! - & next prev * / % + - . < <= > >= == != && || ?: = *= /= %= += -= , >< Expression Syntax The formal syntax of an expression follows. Each of the elements will be described in detail in later sections. Chapter 4 Expressions 35 primary-expression: lvalue function-name ( <argument-list> ) subscript-list ( <argument-list> ) argc string-constant integer-constant float-constant date-constant next ( symbol ) prev ( symbol ) ! primary-expression - primary-expression ( expression ) symbol: symbol-table-name ^ <subscript-list> subscript-list lvalue: symbol argv [ expression ] argument-name local-variable-name function-name: name function-name ^ <name> subscript-list name <subscript-list> ^ <name> <subscript-list> [ expression ] argument: assignment-expression & lvalue argument-list: argument <argument-list> , <argument> multiplicative-expression: primary-expression primary-expression * multiplicative- expression primary-expression / multiplicative- expression primary-expression % multiplicative- expression additive-expression: multiplicative-expression multiplicative-expression + additive- expression multiplicative-expression - additive- expression multiplicative-expression . additive- expression 36 Nadir Reference Manual relational-expression: addition-expression addition-expression < relational-expression addition-expression <= relational-expression addition-expression > relational-expression addition-expression >= relational-expression equality-expression: relational-expression relational-expression == equality-expression relational-expression != equality-expression logical-and-expression: equality-expression equality-expression && logical-and- expression logical-or-expression: logical-and-expression logical-and-expression || logical-or- expression conditional-expression: logical-or-expression logical-or-expression ? expression : conditional-expression assignment-expression: conditional-expression lvalue = assignment-expression lvalue *= assignment-expression lvalue /= assignment-expression lvalue %= assignment-expression lvalue += assignment-expression lvalue -= assignment-expression lvalue .= assignment-expression expression: assignment-expression expression , assignment-expression Primary Expression primary-expression: lvalue function-name ( <argument-list> ) subscript-list ( <argument-list> ) argc string-constant integer-constant float-constant date-constant next ( symbol ) prev ( symbol ) ! primary-expression - primary-expression ( expression ) Chapter 4 Expressions 37 Lvalue An lvalue is the term given to an object that may be specified on the left hand side of an assignment expression. lvalue: symbol argv [ expression ] argument-name local-variable-name argv argv is a special type of variable that allows one of a macro's arguments to be referenced using an ordinal value. The expression after argv is converted an integer and defines which argument is to be used. If zero, the first argument is referenced, if one, the second argument is referenced, and so on. If the expression is greater than or equal to the number of arguments passed, the null value is returned. The other options for lvalue specify either an argument, a local variable or a symbol name. If the name does not contain a caret, or subscripts, the name will be an argument or a local variable. It is an argument if the name is in the arg-name- list specified with the Define keyword. Symbol A symbol is an item that is stored in a symbol table. It has the following syntax. symbol: symbol-table-name ^ <subscript-list> subscript-list For symbol names, the name may start with a symbol table name followed by a caret and a subscript list, or may be a subscript list where the symbol table name is subscripted. The symbol table name may be a system defined table, univ, glob, parm, mdat, mlib, data, temp, or a user defined name. See SymOpen or SymCreate intrinsic functions. subscript-list A subscript-list has the following syntax. subscript-list name <subscript-list> ^ <name> <subscript-list> [ expression ] 38 Nadir Reference Manual The intention is that a subscript-list can be any combination of caret, names and expressions in brackets []. Two names cannot appear next to each other, and a symbol cannot contain a single name. Subscripting allows the actual name of the symbol to be evaluated, by concatenating the components together. When a symbol name is evaluated, it must contain at least one caret, the component before the first caret specifying the name of the symbol table. Function Call A function call is specified when a name or subscript-list is followed by parenthesis enclosing an optional argument list. function-name ( <argument-list> ) subscript-list ( <argument-list> ) The function name specifies an intrinsic function built into the Nadir executable using the Developer's Kit, or a user defined function created by processing the Define keyword. The function name may contain carets. If a function name does not contain a caret, Nadir searches for an intrinsic function and then for a user written function in mdat. If it is not found, and a macro library was specified on the command line, mlib is searched. If a caret is present in the function name, the name component before the first caret specifies the symbol table where the function is read from. The name of the function in the symbol table is the function name with the symbol table name and the first caret removed. When the subscript list alternative is used, the subscript-list is evaluated at execution time to provide the name of the function to call. The name evaluated may be an intrinsic function or a user defined function. At execution time, if a function is not found, an error is signalled. A function call always evaluates to a value. If the called function executes a return statement, it is the value of the return expression, otherwise it is the null value. Chapter 4 Expressions 39 Argument List Arguments may be passed to a function. The argument list contains optional arguments separated by commas. argument: assignment-expression & lvalue argument-list: argument <argument-list> , <argument> An argument may be either an assignment expression, or an & followed by an lvalue. When the & is used, the lvalue is passed by reference. When a variable is passed by reference, the called function may modify the value or contents of the variable. Symbol names, local names, or argument names may be passed by reference. If the assignment expression form is used, the value is passed. If the argument is not specified, the null value is assumed. The following table shows some valid argument lists. Argument Remarks List () no arguments (a) 1 argument (,) 2 null arguments (b,) 2 arguments, last one null (a,b) 2 arguments (,b) 2 arguments, first one null argc argc is a special word that returns the number of arguments passed to the function that it occurs in. next The next operator is used to find the next symbol in a symbol table. next ( lvalue ) The lvalue must specifiy a symbol name. If it is a subscript list, the evaluated name must contain a caret with the first element of the name specifying a valid symbol table. 40 Nadir Reference Manual The return value is a string containing the next name after the lvalue. The return value of next does not include the symbol table name. If lvalue is the last symbol in the table, the null value is returned. See the example of next in Subscripting Symbol Table Names in the Language Overview chapter. prev The prev operator is used to find the previous symbol in a symbol table. prev ( lvalue ) The lvalue must specifiy a symbol name. If it is a subscript list, the evaluated name must contain a caret, with the first element of the name specifying a valid symbol table. The return value is a string containing the previous name before the lvalue. The return value of prev does not include the symbol table name. If lvalue is the first symbol in the table, the null value is returned. Logical negation ! The ! unary operator returns the logical negation of the operand, the following primary expression. ! primary-expression The result is a boolean value. The primary- expression is converted to a boolean, and then a logical negation is performed. i.e. True becomes false, false becomes true. Unary minus - The unary minus operator returns the negative of the operand. - primary-expression If the primary expression is not an integer, float or date, zero is returned. Parenthesis Parenthesis () may be used to override the precedence of an operator, or to change the order of evaluation. The following table shows some examples. Chapter 4 Expressions 41 Expression Evaluation Steps a + b * c b multiplied by c, then added to a (a + b) * c b added to a, then multiplied by c a + b + c b added to a, then c added. a + (b + c) c added to b, which is added to a Multiplicative Expression The three multiplicative operators are * / and %. multiplicative-expression: primary-expression primary-expression * multiplicative- expression primary-expression / multiplicative- expression primary-expression % multiplicative- expression The operands are converted using the arithmetic conversion rules for arithmetic operators. The * operator produces the product of the two operands. The / operator produces the quotent when the first operand is divided by the second operand. If the second operand is zero, the result will be zero. The % or modulus operator produces the remainder when the first operand is divided by the second operand. If the second operand is zero, the result will be zero. If the operands are floats, x % y is the remainder f, where x = ay + f for some integer a and 0 <= f < y. eg 5.0 % 2.0 is 1.0 Additive Expression The three additive operators are + , - and ., the fullstop. additive-expression: multiplicative-expression multiplicative-expression + additive- expression multiplicative-expression - additive- expression multiplicative-expression . additive- expression 42 Nadir Reference Manual For + and -, The operands are converted using the arithmetic conversion rules for arithmetic operators. The + operator produces the sum of the two operands. The - operator produces the difference, when the second operand is subtracted from the first. The . operator converts the operands to strings, if necessary, and concatenates them, forming a string result. Relational Expression The four relational operators are <, <=, >, >= relational-expression: additive-expression additive-expression < relational-expression additive-expression <= relational-expression additive-expression > relational-expression additive-expression >= relational-expression The operands are converted using the arithmetic conversion rules for comparison operators. The type of comparision performed depends on what types the operands are converted to. The result of a relational operator is a boolean value. The operators are described in the following table. a < b if a is less than b, true is returned, else false is returned. a <= b if a is less than or equal to b, true is returned, else false is returned. a > b if a is greater than b, true is returned, else false is returned. a >= b if a is greater than or equal to b, true is returned, else false is returned. Chapter 4 Expressions 43 Equality Expression The two equality operators are == and !=. These have a lower precedence than the relational operators. equality-expression: relational-expression relational-expression == equality-expression relational-expression != equality-expression The operands are converted using the arithmetic conversion rules for comparison operators. The type of comparision performed depends on what types the operands are converted to. The result of an equality operator is a boolean value. The operators are described in the following table. a == b if a is equal to b, true is returned, else false is returned. a != b if a is not equal to b, true is returned, else false is returned. Logical And Expression logical-and-expression: equality-expression equality-expression && logical-and- expression The logical and operator is &&. The result is a boolean value, true if both operands are true, otherwise the result is false. An operand is converted to a boolean value when the test for true is performed. If the first operand is false, the second operand will not be evaluated, and false will be the result. Logical Or Expression logical-or-expression: logical-and-expression logical-and-expression || logical-or- expression 44 Nadir Reference Manual The logical or operator is ||and has a lower precedence than logical and, &&. The result is a boolean value, true if either of the operands are true, otherwise the result is false. An operand is converted to a boolean value when the test for true is performed. If the first operand is true, the second operand will not be evaluated, and true will be the result. Conditional Expression conditional-expression: logical-or-expression logical-or-expression ? expression : conditional-expression In the expression a ? b : c, a is evaluated, and converted to a boolean value. If the value of a is true, expression b is evaluated, and is the result of the conditional expression. If a is false, expression c is evaluated, which becomes the result of the conditional expression. Assignment Expression assignment-expression: conditional-expression lvalue = assignment-expression lvalue *= assignment-expression lvalue /= assignment-expression lvalue %= assignment-expression lvalue += assignment-expression lvalue -= assignment-expression lvalue .= assignment-expression The assignment expressions are used to assign a value to the argument, variable or symbol specified by the lvalue operand. When the assignment operator = expression is evaluated, the assignment-expression is evaluated, and is stored in the variable specified by the lvalue. The result of the expression is the value of the lvalue after the assignment. The other assignment operators are *=, /=, %=, +=, -= and .=. Each of these are an arithmetic operator followed by an equals sign. a op= b has the same result as a = a op b. Chapter 4 Expressions 45 Expression expression: assignment-expression expression , assignment-expression The lowest precedence operator is the comma operator. An expression is a list of one or more assignment-expressions, separated by the comma operator. Each of the assignment-expressions are evaluated, starting from the left, and proceeding to the right. The result of the expression is the result of the last assignment-expression. 46 Nadir Reference Manual CHAPTER 5 STATEMENTS The Define keyword in the input file is used to define a user written function, sometimes referred to as a macro. The syntax of the Define keyword includes a compound statement. This compound statement specifies the processing to be performed by the function. The compound statement may contain a number of statements, performed in the order written. The syntax of the statements follow. Each of the statements are described in detail later in this chapter. statement: compound-statement label-statement null-statement expression-statement return-statement if-statement while-statement do-statement for-statement switch-statement case-statement default-statement break-statement continue-statement goto-statement compound-statement: { <statement-list> } statement-list: statement statement-list statement label-statement: label-name : <statement> null-statement: ; expression-statement: expression ; return-statement: return <expression> ; if-statement: if ( expression ) statement <else statement> Chapter 5 Statements 47 while-statement: while ( expression ) statement do-statement: do statement while ( expression ) ; for-statement: for ( <expression> ; <expression> ; <expression> ) statement switch-statement: switch ( expression ) statement case-statement: case expression : statement default-statement: default : statement break-statement: break ; continue-statement: continue ; goto-statement: goto label-name Compound Statement compound-statement: { <statement-list> } statement-list: statement statement-list statement A compound statement is an optional list of statements enclosed in matching braces {}. Syntactically, a compound statement is treated as a statement. For example, in the while statement, a statement is required. A compound statement is used in this case where the body of the while loop contains a number of statements. A compound statement is used to define the processing to be performed by a function in the Define keyword. Label Statement label-statement: label-name : <statement> 48 Nadir Reference Manual A statement may be labelled by using a label followed by a colon. A label-name is a valid lexical name. The same label name may not be used more than once in a function definition. The label-name may then be used as the target of the goto statement but only within the function that it is defined in. Null Statement null-statement: ; The null statement consists of a semi-colon. It does nothing and is used in situations where the syntax of a statement requires a statement, but no processing is necessary. Expression Statement expression-statement: expression ; An expression statement is an expression followed by a semicolon. The expression is evaluated, and control passed to the next statement. Return Statement return-statement: return <expression> ; The return statement is used to pass control from a function to the calling function. If the optional expression is present, it is evaluted, and the result becomes the return value for the function. If there is no expression, the null value is returned. If a function does not have a return statement, return is made after the last statement in the function is executed. The null value is returned. Chapter 5 Statements 49 If Statement if-statement: if ( expression ) statement1 <else statement2> The if statement allows conditional processing based on the result of an expression. The expression is evaluated, and the result is converted to a boolean value. If the value is true, statement1 is executed. If the value is false, and the optional else statement2 is present, statement2 is executed. While Statement while-statement: while ( expression ) statement The while statement is a pre tested loop statement. The expression is evaluated and converted to a boolean value. If the value is true, the statement is executed. If there are no statements that pass control out of the loop, the expression is evaluated again. The loop continues until the expression evaluates to false. When this occurs, contol is passed to the statement after the while statement. Do Statement do-statement: do statement while ( expression ) ; The do statement is a post-tested loop statement. The statement is executed. If there are no statements that pass control out of the loop, the expression is then evaluated and converted to a boolean value. If the value is true, control passed to the beginning of the statement, and the statement is then executed again. If the value is false, control is passed to the next statement. 50 Nadir Reference Manual For Statement for-statement: for ( <expression1> ; <expression2> ; <expression3> ) loop-statement The for statement is pre-tested loop statement. expression1 is the initializing expression. If it is present, it is executed. expression2 is the test expression. If present, it is evaluated and converted to a boolean value. If it is not present, a true value is assumed. If the value is true, the loop-statement is executed. expression3 is the increment expression. After the loop-statement is executed, the increment expression, if present, is evaluated. Control is then passed back to the step where the test expression is evaluated and tested. Switch, Case and Default Statements switch-statement: switch ( expression1 ) statement1 case-statement: case expression : statement2 default-statement: default : statement3 The switch statement allows branching to sections of code marked by case or default statements, based on the value of the switch expression. In statement1 there can optionally be one default statement, and any number of case statements. expression1 is evaluated. It is then tested for equality with each of the expressions in any case statements. These expressions are evaluated in the order they occur in statement1. When equality is found, statement2 in the case statement is executed. Execution then continues until the end of statement1. Any case expressions encountered are not evaluated, but any statement2 in following case statements or a statement3 will be executed. Chapter 5 Statements 51 To stop execution after a statement2 in a case statement, the break statement may be used to transfer control to after statement1. If no equality is found with case expressions, and there is a default statement, control passes to the statement3. If there is no default statement, control passes to the end of statement1. Break Statement break-statement: break ; A break can only be used within a while, do or for loop, or a switch statement. It terminates the nearest enclosing loop or switch statement. Continue Statement continue-statement: continue ; A continue statement can only be used within a while, do or for loop. In while and do loops, it transfers control to the test expression. In for loops, control is passed to the increment expression. With nested loops, the continue statement belongs to the nearest enclosing loop. Goto Statement goto-statement: goto label-name The goto statement transfers contol to the statement labeled with the label-name. The label must be defined in the same function as the goto statement. 52 Nadir Reference Manual CHAPTER 6 SYSTEM INTRINSIC FUNCTIONS This chapter details the basic set of intrinsic functions that is always present in Nadir. With the Developer's Kit, other modules of intrinsic functions may be added to the system. Bunch Function Bunch a number of fields into one field. Syntax Bunch(arg ...) Returns The bunch formed by the given arguments Remarks This allows a number of fields to be stored in one field. A bunch may be broken into its components by using the Unbunch function. Example l_ocal = Bunch(1, 2, 3, "abcd", 45.2); This will store a bunch of 5 elements in the local variable l_ocal. DateDay Function Get day component of date Syntax DateDay(date) Returns The day number in the month of the date argument. Example DateDay("3/5/1990") would return 3 if dd/mm/yyyy is the date format. DateDayName Function Get day name of a date Syntax DateDayName(date) Returns The day name of the date argument. Example DateDayName("18/1/1993") would return "Monday" Chapter 6 System Intrinsic Functions 53 DateMonth Function Get month component of date Syntax DateMonth(date) Returns The month number of the date argument. Example DateMonth("3/5/1990") would return 5 if dd/mm/yyyy is the date format. DateMonthEnd Function Get the month end date. Syntax DateMonthEnd(date) Returns Date of the last day of the month of the date argument. Example DateMonthEnd("3/5/1990") would return "31/5/1990". Note that the value returned is really a date, not a string. DateMonthName Function Get month name of a date Syntax DateMonthName(date) Returns The month name of the date argument. Example DateMonthName("18/1/1993") would return "January" DateMonthStart Function Get the month start date. Syntax DateMonthStart(date) Returns Date of the first day of the month of the date argument. Example DateMonthStart("3/5/1990") would return "1/5/1990". Note that the value returned is really a date, not a string. 54 Nadir Reference Manual DateToday Function Return today's date. Syntax DateToday() Returns Today's date. DateYear Function Get year component of date Syntax DateYear(date) Returns The year number of the date argument. Example DateYear("03/05/1990") would return 1990. Dump Function Dump values to the Nadir output file. Syntax Dump(arg...) Returns Null Value Remarks This routine is used to dump fields to the output file. The format of the output is such that the type of field can be determined. This function may be used for dump and load type operations with symbol tables. Dump attempts to limit the width of the standard output to 80 characters. If strings are longer, Dump will continue strings like continued strings in the Nadir language. Example Dump("ab\ncd") "ab\ncd" Dump("very long string") "very lo\ ng string" Dump(123) 123 Dump(123.45) 123.45 Dump("1/1/1992") "01/01/1992" Chapter 6 System Intrinsic Functions 55 Dump(Bunch(1,1.2,"abc")) Bunch(1, 1.2, "abc") In the second example, the continuation is really performed at the 80th character of a long string. The example is given to show how a long string is continued on the next line. Explode Function Break a string into components Syntax Explode(str, delimiter, &var1, &var2, &var3 ...) Returns The number of components in str that are separated by the delimiter character. This is the same as the number of delimeters + 1. Remarks If a delimiter is not specified, "^" is assumed. var1 will be set to the first component, var2 to the second and so on. If there are more variables than components, remaining variables are set to the null value. This function may be used to break a variable name into components. Example explode("fred^mary^joan", "^", &loc1, &loc2, &loc3) would set loc1 to "fred", loc2 to "mary", loc3 to "joan" and return 3. Exit Function Exit the Nadir program. Syntax Exit(msg, retCode) Returns Does not return. Remarks If the msg argument specified, it is displayed as an abnormal termination message. The Nadir program is exited. The exit occurs even if cycling is specified on the command line when starting Nadir. If retCode is specified, it will be the exit status of the Nadir program. If it is not specified a value of zero will be returned. 56 Nadir Reference Manual FieldType Function Get field type. Syntax FieldType(arg) Returns The field type of the argument. Will be one of the following "STRING" "INT" - integer field. "FLOAT" "DATE" "BUNCH" Remarks The type returned is the actual type of the field. For example, if arg is a string that contains "123", "STRING" will be returned. FileClose Function Close file opened with FileOpen Syntax FileClose(handle) Returns Null value. Remarks The file, specified by the handle argument is closed. The handle is the value returned from the FileOpen function. FileColumn Function Return current column in a file. Syntax FileColumn(handle) Returns The column number, 0 for first column. Remarks The column number is returned for the file opened with the handle specified by the handle argument. The current column is maintained for a file opened for output. It is reset to zero when a newline is printed to the file. Any other character printed to the file increments the column number by 1. FileDump Function Dump fields to a file. Chapter 6 System Intrinsic Functions 57 Syntax FileDump(handle, arg ...) Returns Null value Remarks Same as Dump function, except output is to the file specified by the handle argument. FileIndentSet Function Set the indent number for a file. Syntax FileIndentSet(handle, indent) Returns The original value of the indent number. Remarks The indent number is set for the file opened with the handle specified by the handle argument. The indent argument specifies the value that the indent column number is to be set to. When Nadir is outputting to a file, if the character to output is not a newline, and the current column number is zero, Nadir will output the indent number of spaces before the character is output. FileLineGet Function Get next line from file opened with FileOpen Syntax FileLineGet(handle, &var, lnlFlag) Returns Returns error status, 0 (zero) if line was read successfully, non zero for end of file. Remarks The line is read from the file opened with the handle specified by the handle argument into the variable, var. If lnlFlag, leave newline flag, is false, the newline character that separates lines is removed. This is the default action. If lnlFlag is true, any newline character at the end of the buffer is not removed. Note that the variable has to be passed by reference, if its value is to be set. FileOpen Function Open a text file for reading or writing. 58 Nadir Reference Manual Syntax FileOpen(fileName, mode) Returns The file handle to be used in subsequent FileRead, FileLineGet, FilePrint, FileDump and FileClose function calls. If the file cannot be opened, zero is returned. Remarks fileName specifies the name of the file to be opened. If no path information is present in fileName, the file is opened in the directory specified by the -D command line switch, or the current directory if -D was not used. The mode string may contain a word. The first character of the word can specify one the following types. Case is not significant. "R"ead Existing file is opened for reading. "W"rite File is created and opened for writing. "A"ppend Existing file is opened for append. Information is written to the end of the file. If the file does not exist, file will be created. Example Following example demonstrates the FileOpen, FileLineGet, FilePrint and FileClose functions. When it is processed, c:\autoexec.bat is printed to the Nadir output file, and is also printed to a file \tmp\junk. Define TestFile() { if (!(infile = FileOpen(`c:\autoexec.bat`, "read"))) Signal("Could not open input file"); if (!(outfile = FileOpen(`\tmp\junk`, "write"))) Signal("Could not open output file"); while (!FileLineGet(infile, &buff)) { Print(buff, "\n"); FilePrint(outfile, buff, "\n"); } FileClose(infile); FileClose(outfile); } TestFile FilePrint Function Print fields to a file. Syntax FilePrint(handle, arg ...) Chapter 6 System Intrinsic Functions 59 Returns Null value Remarks Same as Print function, except output is to the file specified by the handle argument. FileRemove Function Remove a file. Syntax FileRemove(fileName) Returns Returns error status, 0 (zero) if file was deleted successfully, non zero if it was not deleted. Remarks fileName specifies the name of the file to be deleted. FloatToInt Function Convert a float to an integer. Syntax FloatToInt(arg) Returns The integer value of arg. If arg is not a float, or cannot be converted to a float, zero is returned. Level Function Get procedure level. Syntax Level() Returns An integer, the level within the execution hierarchy. The outermost level is level 0. 60 Nadir Reference Manual Example Define Level00() { Print("Entering Level00, Level is ", Level(), "\n"); Level01(); Print("Leaving level00, Level is ", Level(), "\n"); } Define Level01() { Print(" In Level01, Level is ", Level(), "\n"); } Level00 when processed, will output Entering Level00, Level is 0 In Level01, Level is 1 Leaving level00, Level is 0 LineCurr Function Get contents of current line in input file Syntax LineCurr(&var, lnlFlag) Returns Returns null value. Remarks The current line being processed in the Nadir input file, is copied into the specified variable,var. If lnlFlag, leave newline flag, is false, the newline character that separates lines is removed. This is the default action. If lnlFlag is true, any newline character at the end of the buffer is not removed. Note that the variable has to be passed by reference, if its value is to be set. See example in LineGet to see how a macro can be used to process lines from the input file. LineGet Function Get next line from the input file. Syntax LineGet(&var, lnlFlag) Returns Returns error status, 0 (zero) if line was read successfully, non zero for end of file. Chapter 6 System Intrinsic Functions 61 Remarks The next line is read from the Nadir input file, and the resulting line is copied into the specified variable, var. If lnlFlag, leave newline flag, is false, the newline character that separates lines is removed. This is the default action. If lnlFlag is true, any newline character at the end of the buffer is not removed. Note that the variable has to be passed by reference, if its value is to be set. The line is initially read into the buffer used by lexical analysis when processing the Nadir input file. Using this macro, in conjunction with LineCurr, allows the user to process the input file by lines in a user written macro. Example When the following input is processed, Define Testit() /* Testit reads lines after it is invoked, and outputs them prefixed with 4 percent signs. This finishes with a line containing EndTestit */ { LineCurr(&buff); do { if (buff == "EndTestit") { LineGet(); TokenNext(); /* move lexical analysis off token after Testit word, and onto token after EndTestit line */ return; } Print("%%%%",buff,"\n"); } while (!LineGet(&buff)); } aaaaaaaaaa Testit bbbbbbbbbb cccccccccc EndTestit dddddddddd The following output is produced. aaaaaaaaaa %%%%bbbbbbbbbb %%%%cccccccccc dddddddddd 62 Nadir Reference Manual LineNum Function Get line number in the input file. Syntax LineNum() Returns Returns the line number of the current line being processed in the input file. The first line in the file is line number 1. OutputColumn Function Return current column in the output file. Syntax OutputColumn() Returns The column number, 0 for first column. Remarks The current column is maintained for the output file. It is reset to zero when a newline is printed to the output file. Any other character printed to the output file increments the column number by 1. OutputIndentSet Function Set the indent number for the output file. Syntax OutputIndentSet(indent) Returns The original value of the indent number. Remarks The indent argument specifies the value that the indent column number is to be set to. When Nadir is outputting to the output file, if the character to output is not a newline, and the current column number is zero, Nadir will output the indent number of spaces before the character is output. PreProcessSet Function Set pre-process flags. Symtax PreProcessSet(string) Returns Returns a string, the original value of the pre- process mode flags. Chapter 6 System Intrinsic Functions 63 Remarks The string argument specifies the required value for the pre-process flags. It may conain the following characters :- Char Meaning d Define keyword in input file is ignored e Eval is ignored i If, Elseif, Else and Endif are ignored. By ignoring all keywords, only user written macros are expanded. Using this feature, a user can pre process Nadir code. Pre-process flags may be initially set by using the -n command line switch. Example The following example defines a couple of useful macros that may be used to change the mode. Define PreProcessOn(flags) /* turns on pre processing */ { PreProcessSet(flags ? flags : "dei"); } Define PreProcessOff /* turns off pre processing */ { PreProcessSet(""); } Define MyMacro(a,b) /* pre processing off by default */ { return a + b; } PreProcessOn Define Testit { a = MyMacro(4, 3); } When the above is processed (without the -n switch), the following output is produced. Define Testit { a = 7; } Print Function Print to the Nadir output file. Syntax Print(arg ...) Returns Null Value 64 Nadir Reference Manual Remarks Print outputs all the given arguments to the Nadir output file. If arg is a bunch, the elements of the bunch are printed, separated by commas, and enclosed in parentheses, "(" and ")". Example Code Result Print(1, 2, "abc") 12abc Print("abc\ndef") abc def myBunch = Bunch(1,2,3,"abc"); (1, 2, 3, Print(myBunch) abc) Process Function Performs Nadir input to output processing on strings. Syntax Process(input, &output) Returns Returns a string. If no error, returns a null string. If an error occurs either in the syntax, or execution of the arguments, the text of the error is returned. Remarks The input is converted to a string, if necessary. This string is then processed as if it had occurred in Nadir's input file. The ouput of the processing is returned in the output argument. This variable has to be passed by reference. If an error occurs in the execution, any resource that was allocated may not be released. For simple expressions, no resources would probably be involved, however if functions are called, access counts will not be decremented, and any handles, memory etc will not be released as processing stops when the error occurs. The safest method is to call Signal with the error message to restart the system. Example myString = `Eval(DateToday() - "15/10/1955")`; Process(myString, &result); This example, when written in a function, compiles and runs the string in myString as if it had occurred in the input file. The age in days, of a person born on 15 October 1955 is written to the variable called result. Chapter 6 System Intrinsic Functions 65 Signal Function Display an error message, and restart depending on startup parameter. Syntax Signal(arg) Returns Does not return. Remarks The argument, arg, is converted to a string and is displayed as a condition message. If cycling was specified on the command line, the Nadir program is restarted. If cycling was not specified, the Nadir program is terminated. Spawn Function Execute another program. Syntax Spawn(string, silent) Returns An integer, the called program's exit status or - 1. -1 is returned if the program could not be run, either the argument list to the program was too long, the path or file could not be found, or there was not enough memory. Remarks If used under Windows, this function is the same as System. Under DOS, it has different behaviour to System. The string is parsed as if it was a command. The first word specifies the program to run. The other words are built into list of arguments, and the runtime library function spawnvp is called to execute the program. The purpose of this function is to allow programs to be called and their exit status to be examined. The silent argument is a boolean value. If true, it is assumed that the spawned program will not perform any output to the screen. The screen contents are not saved before spawning or restored after the program has finished. SpawnRestart Function Execute another program and then restart Nadir. Syntax SpawnRestart(string, silent) 66 Nadir Reference Manual Returns Resturn is never made, since system is restarted. Remarks This function is available under DOS only. It is the same as the Spawn function, except all data files are closed before the program is invoked. On return, Nadir is restarted, if the cycle on errors switch was specified on the command line. StrCat Function Concatenate strings. Syntax StrCat(arg ...) Returns The string formed by concatenating the arguments. Remarks Arguments are converted to strings. This function was used before the concatenation operator was developed. Example Print(StrCat("abc", 12, "def")); will print abc12def StrFromAscii Function Convert an ascii value to a character string. Syntax StrFromAscii(arg) Returns A character string which contains the byte with the ascii value of the integer argument. Remarks arg is converted to an integer. If arg is not a valid integer, the null value is returned. If arg is greater than 255, the least significant byte is placed in the result. Example StrFromAcsii(48) returns "0" StrFromLit Function Convert a literal to a string. Syntax StrFromLit(string) Returns The string formed by converting the string literal argument. Chapter 6 System Intrinsic Functions 67 Remarks This function performs the reverse of StrToLit. i.e. If the characters backslash lowercase n are in the argument, the returned string will contain 1 character, the newline character. A sequence of backslash newline is dropped. This is how long strings are continued. The valid sequences in the string literal are :- \a audible (bell) character. \b backspace. \f formfeed. \n newline. \r carriage return. \t tab. \v vertical tab. \\ backslash. \' single quote. \" double quotes. \x 2 digit hexadecimal constant follows \nnn 3 digit octal constant. Since the function does not error, there are slight differences to the lexical analysis performed on string literals in the Macro Language. If the string ends with a single backslash, a backslash is output. If there are not 2 valid hex characters after a \x, the value found so far is output to the result. eg "\xaz" would produce the same result as "\x0az", and "\xzz" would produce the same output as "\x00zz". Similarly, the conversion routine continues if there are not 3 valid octal characters for the octal constant. StrFromQuoted Function Convert from a quoted string to a string. Syntax StrFromQuoted(string) Returns The string formed by converting the quoted string argument. Remarks A quoted string begins and ends with a matching single quotes, double quotes or accents. If string is not one of these, the return value will be the same as string. 68 Nadir Reference Manual If string has matching single or double quotes, these are dropped, and the remaining characters are converted to a string using the same rules as StrFromLit. If string has matching accents, the accents are dropped. Remember that when processing input, arguments to macros are either strings or quoted strings. This function may be used to convert quoted string arguments passed to a macros. Examples Following results are the output from a Print(StrFromQuoted(Arguments)); For the first example it would be Print(StrFromQuoted("\"abc\"")); The double quotes have to be escaped to get the double quotes into the string. Arguments No of Printed No of contain chars Result chars "abc" 5 abc 3 "abc\ndef" 10 abc 7 def 'abc\x20def' 12 abc def 7 `abc 9 abc 7 def` def abc\ndef 8 abc\ndef 8 If the following input file is processed Define PrintIt(arg) { Print(StrFromQuoted(arg)); } PrintIt("abc\ndef") Quoted String PrintIt(abc\ndef) Not a quoted string The following output file would be produced abc def Quoted String abc\ndef Not a quoted string StrLen Function Obtain string length. Syntax StrLen(string) Returns The number of characters in the string argument. Chapter 6 System Intrinsic Functions 69 StrMatch Function Test if string matches a regular expression type pattern. Syntax StrMatch(pattern, string) Returns 1 if string matches the pattern, 0 if it doesn't. Remarks The second argument is the string that is matched against the pattern. Characters that have special meaning in the pattern are :- ? Match any character in this position. * Match zero or more characters. ! If first character in pattern, negates match expression. Has no significance if not the first character in pattern or not the first character after [ \ Quotes following character so it is taken literally | Logical or between two or more patterns to use to match the string. eg bob|mary would match either bob or mary [..] Defines a group of characters to match at the current position. The following characters have special meaning inside square brackets. ! If first character negates character set. - Used to specify a range. eg. a-z specifies the chars from 'a' to 'z' inclusive. eg [!-a-z] means not minus sign and not characters a to z. \ Quotes special characters. Examples Pattern String Result ab*cd abcd 1 ab*cd abxxxcdcd 1 ab?cd abcd 0 ab?cd abccd 1 !ab*cd abcd 0 [0-9][0-9]\|[a-z] 34|p 1 StrPos Function Find position of a string in another string. 70 Nadir Reference Manual Syntax StrPos(string, substring) Returns Returns the offset in string of the first occurrence of substring. Remarks Offset 0 means the first character. It the substring is not found in string, -1 is returned. StrSubs Function Extract a string from a string. Syntax StrSubs(string, offset, length) Returns Returns the substring which has length characters at offset characters in string. Remarks The offset of the first character is 0. If offset is too large, the null value is returned. If length is zero, or undefined, the rest of the string after offset is returned. StrToAscii Function Convert a character to an ascii value. Syntax StrToAscii(string) Returns The ascii value of the first byte of the string argument. Remarks StrToAscii returns zero if string has zero length Example StrToAcsii("0aB") returns 48. StrToLit Function Convert string to a literal Syntax StrToLit(string) Returns The string literal, formed by converting the string argument. Remarks A string literal is the string of characters that literally describe the contents of a string. If a string contains a newline character, the string literal will contain 2 characters, a backslash followed by a lowercase n. Chapter 6 System Intrinsic Functions 71 For a list of the sequences that may be output see StrFromLit. If a character is not one of the specified ones like newline, formfeed, vertical tab etc, a hex constant sequence will be output. Example Statement would print Print(StrToLit("Number\nis ", Number\nis 42.02 42.02)); Print("Number\nis ", 42.02); Number is 42.02 StrToLower Function Convert characters to lowercase. Syntax StrToLower(string) Returns The string converted to lowercase. Remarks Any uppercase character is converted to lowercase, any other characters are copied to the return value unchanged. StrToUpper Function Convert characters to uppercase. Syntax StrToUpper(string) Returns The string converted to uppercase Remarks Any lowercase character is converted to uppercase, any other characters are copied to the return value unchanged. SymClose Function Close a symbol table. Syntax SymClose(symtabName) Returns Null value. Remarks The symbol table, specified by symtabName is closed. Access is not possible until SymOpen is performed for the symbol table. SymCreate Function Create a symbol table file, and open for access. 72 Nadir Reference Manual Syntax SymCreate(symtabName, fileName, type, blkSize, buffCnt) Returns Returns an error status. 0 for success, 1 for file already exists. Remarks The function is used to create a symbol table file. After SymCreate, the symbol table is open for use. ie It is not necessary to perform a SymOpen. For an explanation of the arguments, see SymOpen. SymLock Function Lock symbol tables to control access. Syntax SymLock(symtabName, updateFlag ...) Returns Null Value. If return is made, lock requests were granted. Remarks Aruments are pairs of symtabName, eg "univ", and an updateFlag. If updateFlag is true, the user acquires an update lock, otherwise a read lock is acquired. Locks are required if a symbol table is not temporary and not exclusively opened. When an Update lock is acquired, no other user on the system will be able to update the symbol table until the lock is freed. Locks are freed when SymLock is called again, or if ScreenDialogues are used, an SdEdit function call is performed. SymLock unlocks any locks before performing the locks. The function locks the symbol tables in the order they are specified in the argument list. The order in the argument list should be kept consistent in an application to avoid deadlocks. Read locks, when updateFlag is not set, are used for reporting purposes. i.e. another user may get an update lock while you are using the file in this mode. If SymLock is not used, any access to a symbol table file that has not been locked, is locked in Update mode automatically. If the automatic method is used, the order of locking depends on the sequence in which the symbols are updated. When this happens, deadlocks may occur. Chapter 6 System Intrinsic Functions 73 If it is not possible to lock one of the symbol tables, any locks that have already been completed are unlocked, and control is passed to a user written function called SymLockQuery. This routine takes one argument, the filename and should return 0 to retry the lock(s). Any other response will cause a Signal to be performed. SymOpen Function Open a symbol table file for access. Syntax SymOpen(symtabName, fileName, type, blkSize, buffCnt) Returns Returns an error status. 0 for success, 1 for file not found. Remarks symtabName is the name of the symbol table that is being opened. Examples are "univ", "glob", "mdat", "parm", "data", "temp". These are fixed names that have specific meanings to Nadir. A number of user defined names may also be specified. The length is limited to 16 characters. When symbols are referenced, this name is the first component of the symbol name. eg "univ^var^name". fileName specifies the disk file name of the symbol table. If a directory name is not included in the name, the -D parameter specified on the command line is used. If -D was not specified, the current or working directory is chosen. If fileName is not specified, the system default name, or the last name used for the symbol table will be used. The system default is symtabName with the .DAT extension. The fileName argument is ignored for temporary files. A temporary filename is generated. The file is created in the directory specified by the -T command line parameter. If -T was not specified, a temporary file will be created in the current or working directory. If the symbol table is already open, SymOpen will perform a SymClose. The type string contains words separated by any number of non-alpha chars and specifies the type of symbol table that is to be opened. The first character of the word specifies the following types. Case is not significant. 74 Nadir Reference Manual "T"empora File is temporary and deleted when ry closed. If a file is temporary, exclusive use is assumed. SymOpen and SymCreate is the same for temporary files. "E"xclusi When opened has exclusive use. ve May not be shared with other users. If type is not specified, the default type is a permanent, shared file. blkSize defines the size of each block or node in the symbol table file. If not specified, the default size is 512 bytes. blkSize will affect performance and the maximum size of a symbol value. If blkSize is too large, too much memory will be used for buffers, and too much time will be spent searching the node. If blkSize is too small, the symbol table will have too many levels. The size of a symbol name plus its value needs to be less than half the blkSize minus a bit for overheads. blkSize can be changed for an existing symbol table by using the pack or copy function in the Symbol Table Utility, stu. buffCnt specifies the number of buffers that are used when managing the symbol table. If not specified, a default number of 4 is chosen. If a number less than 2 is specified, 2 will be chosen. SymRemove Function Remove a symbol table file from disk. Syntax SymRemove(symtabName, fileName) Returns Returns an error status. 0 for success, non zero if an error occurs. Either the file did not exist, or permission to delete was denied. Remarks If the symbol table, specified by symtabName is opened, SymRemove will close it before performing the delete. If fileName is not specified, the conventions described in SymOpen are followed. symtabName is used to specify an internal slot to use for the operation, fileName defines the disk file that is removed. Chapter 6 System Intrinsic Functions 75 System Function Perform a system call. Syntax System(string, silent) Returns For DOS, return value is zero if call is successful, otherwise non zero. For Windows, return value is zero if call was successful, else the returned value is one more than that returned by the Windows API WinExec function. i.e. Return value is 1 for Out of memory. Remarks If string is not given, the DOS command.com file is executed. Under DOS, be sure that the Nadir input file is not a disk file. Either use the -i switch on the command line when starting Nadir to specify a file, or use System("command<con"). Also if the output is a file, use System("command>con"). If string is present, it is passed as a command to the command processor. Under Windows, the WinExec API function is used. This may be used to start other windows applications, including another copy of Nadir. The silent argument is a boolean value, and is not used by the Windows version. If true, any output from the command is discarded. The screen contents are not saved before executing the command or restored after the command has finished. SystemRestart Function Perform system call and restart Nadir. Syntax SystemRestart(string, silent) Returns Return is never made, since the system is restarted. Remarks This function is available under DOS only. It is the same as the System function, except all data files are closed before the command processor is invoked. On return, Nadir is restarted, if the cycle on errors switch was specified on the command line. 76 Nadir Reference Manual SystemRestart may be used to allow batch files or other programs access to files that the Nadir has open. These functions would include backup, restore and file maintenance. SysType Function Get System Type Syntax SysType() Returns The a string that contains the system type for the Nadir program that is running. Will be one of :- "DOS" running DOS version, n.exe. "WIN" running Windows version, nw.exe and nsys.dll. TaskNum Function Obtain unique task number. Syntax TaskNum() Returns The current task's task number. Remarks On the DOS version, this function always returns 0. Using the Windows version, a number of tasks may be started simultaneously. Task numbers will range from 0 to the maximum number of tasks that may be started minus one. TimeNow Function Get current time Syntax TimeNow() Returns A string containing the current time in format "hh:mm:ss". TokenNext Function Advance to the next token. Syntax TokenNext(comment) Chapter 6 System Intrinsic Functions 77 Returns The error message. If no error occurred, the null value is returned. Remarks Use this function to advance from one token to the next. See the remarks in TokenScanCreate for the effect of TokenNext when TokenScanCreate has not been performed. If the comment argument is true, any comments will be skipped over. If comment is not specified or is false, all the tokens in a comment will be returned. Comments are either any text between /* and */, or between // and a newline character. If tokens in comments are returned, they have to contain valid tokens, for example quoted strings have to be correctly terminated. Note that an empty string contains one token, the end of text token. TokenScanCreate Function Create or initialize a token scan of a string. Syntax TokenScanCreate(string) Returns Null value. Remarks This function creates data structures and copies the string argument. The TokenNext function has to be called to advance to the first token. TokenType, TokenValue, TokenTerm may be used to examine the current token. If TokenNext, TokenType, TokenValue, TokenTerm are called without TokenScanCreate, the tokens in the Nadir input are examined. Nadir input is the string after the -p command line switch, or if that is not specified, the Nadir input file. If TokenScanCreate has been used, TokenScanDestory should be used to free the data structures that have been created. A token scan may be performed within another token scan. 78 Nadir Reference Manual Example The following example shows how the Token functions may be used to lexically analyse a string. It is intended to be the input to Nadir. The second invokation of TestToken will produce an error. Define TestToken(str) { str = StrFromQuoted(str); TokenScanCreate(str); do { if (err = TokenNext()) { Print("error :- ", err); break; } Print(`term = "`, StrToLit(TokenTerm()),`" `, `token = "`, StrToLit(TokenValue()),`" `, `type = `, TokenType(), "\n"); } while (TokenType() != "EOT"); TokenScanDestroy(); } TestToken(" aa\t 123 123.4 \"abcd\" \"20/9/1953\" while") TestToken(" aaaaa ' bbbbb") TokenScanDestroy Function Release the resouces allocated by TokenScanCreate. Syntax TokenScanDestroy() Returns Null value. TokenTerm Function Get the terminator before the current token. Syntax TokenTerm() Returns A string containing the value of the terminator. Remarks The terminator is the whitespace that separates the current token from the previous token. It may be null, for example where there is no whitespace between a name and an operator. See the comments in TokenScanCreate for the effect of TokenTerm when TokenScanCreate has not been performed. Chapter 6 System Intrinsic Functions 79 TokenType Function Get the type of the current token. Syntax TokenType() Returns A string describing the type of the current token. Valid values are shown in the table below. For more information see the Lexical Elements chapter. "NAME" Name, could be a keyword. "OPER" Operator like + or != "STRING" String literal, "abcd\nefg", `qwerty` or 'a' "DATE" Date string "20/9/1953" "FLOAT" Number with a decimal point 123.45 "INT" Integer value 12344 "EOT" End of text. When no errors occur, the last token will have this type. "CHAR" A character that is not one of the above types. Remarks See the comments in TokenScanCreate for the effect of TokenType when TokenScanCreate has not been performed. TokenValue Function Get the value of the current token. Syntax TokenValue() Returns A string containing the value of the current token. Remarks See the comments in TokenScanCreate for the effect of TokenValue when TokenScanCreate has not been performed. Unbunch Function Break a bunch into components. Syntax Unbunch (bunch, &var ...) Returns Number of items in the bunch. If the first argument is not a bunch, 0 is returned. Remarks Used to extract the component parts of the bunch into the variables, which should be passed by reference. 80 Nadir Reference Manual If the first argument is not a bunch, the first variable is set to that value. Any extra variables are set to the null value. Example l_ocal = Bunch(1, 2, "abcd", 45.2); r = Unbunch(l_ocal, &loc1, &loc2, &loc3, &loc4, &loc5); This code would set loc1 to 1, loc2 to 2, loc3 to "abcd", loc4 to 45.2, and loc5 to the null value. r would be set to 4. Chapter 6 System Intrinsic Functions 81 APPENDIX A SYSTEM PARAMETERS System parameters are values in the parm symbol table that are read when Nadir starts processing. The following section describes each of these parameters. mdir^threshold The mdir file is an internal work file that keeps track of the code and data portions of functions that are loaded in memory. If the threshold value is not specified, or zero, a function that is loaded from the mdat file into memory is retained in memory until the Nadir program is ended. The exception to this rule is when a function is redefined using the Define keyword in the input file after it has been loaded into memory, in which case the system will free the current version in memory, if it is not in use at the time of being redefined. When a threshold is specified, the system attempts to limit the use of memory to store function code and data to the number of bytes specified by the threshold. i.e. If threshold is 100000, the system will limit the memory used to store code and data areas to 100000 bytes. To do this, the following processing is performed. When a function is called, and it is not in memory, it is loaded into memory and the memory usage statistic updated. Each time it is called a use count is incremented. Each time a return is made from a function, its use count is decremented. When a function is called, and the memory usage is above the threshold, all functions in memory with a use count of zero are removed, and the memory usage statistic updated accordingly. date^format If date^format is "u", the US date format is used. When dates are input or output, the format mm/dd/yyyy is used. If date^format is not "u', the Australian format dd/mm/yyyy is used. 82 Nadir Reference Manual gui^browser Name of a program that can be used for browsing text files in the Windows version. This program will take one command line argument, the name of the file to browse. text^browser Name of a program that can be used for browsing text files in the DOS version. This program will take one command line argument, the name of the file to browse. word^Define If specified, defines what word to use for the Define keyword when processing input. The allows the user to redefine the Define keyword to another word. eg DEFINE_MACRO. word^Eval If specified, defines what word to use for the Eval keyword when processing input. word^If If specified, defines what word to use for the If keyword when processing input. word^Elseif If specified, defines what word to use for the Elseif keyword when processing input. word^Else If specified, defines what word to use for the Else keyword when processing input. word^Endif If specified, defines what word to use for the Endif keyword when processing input. Appendix A System Parameters 83 APPENDIX B SYSTEM LIMITS Windows Tasks Maximum Windows tasks - 16 tasks. This is the number of times the Windows version of the program can be started simultaneously. Handles Number of handles - 64 handles. The handle manager manages the internal pool of handles. A handle is returned from the FileOpen intrinsic functions, as well as the SdCreate, MsgCreate, PfCreate and PdCreate functions described in the function reference. File Handles Number of file handles - 16 handles. This is the number of handles that may be opened using the FileOpen intrinsic function. Symbol Tables Maximum number of symbol tables open at one time - 7 fixed, 16 user definable. The fixed symbol tables are univ, glob, parm, mdat, mlib, data and temp. Up to 16 other tables may be opened and accessed at the same time. Symbol Name Size Maximum size of the internal representation of a symbol name - 128 bytes. The internal representation will differ slightly from the text representation of a symbol name. The length of the internal representation of each component can be calculated using the following table. The caret separator is not stored in the internal form. string string length plus 2 integer 5 date 5 float 9 84 Nadir Reference Manual B-tree Levels Maximum levels in b-tree - 10 levels. A b-tree structure is used to store symbol names and values. The number of levels in the b-tree affects the total number of symbols that can be stored in a data file. It is felt that this will be hard to exceed. B-tree Nodes Maximum number of nodes - 65535 nodes. The number of nodes or blocks in a symbol table file is limited to 16 bits. For 4096 byte blocks the maximum file size is 256Mbytes. B-tree Node Size Maximum node size - 65500 bytes. This is the size in bytes of a block in the file, used to store one node of the b-tree structure. By increasing the size of a node, the levels in the b-tree can decrease, but the node search time and the memory requirements will increase. Symbol Name and Value Lengths The combination of the length of the internal representation of the symbol name and value in a symbol table is limited by the following :- nameLen + valueLen + 4 has to be less than (blkSize - 10) / 2 The internal lengths for the different value types are :- string string length plus 1 integer 5 date 5 float 9 String Size Maximum string size - 2048 bytes. This is the maximum length of a string value. The limit is used internally in a number of places, including string conversions, eg StrToLit, StrFromLit, PfFormat and Sd functions that deal with editing strings. Operand Stack Size Default stack size - 4096 bytes. Appendix B System Limits 85 This size can be specified by the user by using the -So command line switch. The maximum size is 65500. The operand stack is used to hold the results of expression evaluation. The items on the stack use the number of bytes shown in the following table. string string length plus 3 integer 7 date 7 float 11 Local Value Stack Size Default stack size - 4096 bytes. This size can be specified by the user by using the -Sl command line switch. The maximum size is 65500. The local value stack is used to store the values of local variables for all the active functions. The element size of each item on the stack is the same as for the Operand Stack. Parameter Value Stack Size Stack to store parm values - 512 bytes. The parameter value stack is used to store the values of the parm symbols read when Nadir starts. The parameters described in the System Limits Appendix in the Language Reference and the Function Reference are stored in this stack. Parser Word Size Maximum word size - 2048 bytes. The word is used to store the current token from the input file. The item most likely to reach the limit is a string literal. Parser Line Size Maximum line size - 512 bytes. This is the size of the buffer used to read data from the Nadir input file. If a line is longer than this value, it is a lottery whether Nadir will correctly process it. i.e. Is a token split into two when 512 characters are read? 86 Nadir Reference Manual Parser Argument Names Stack to store argument names - 512 bytes. The argument names for the function being compiled is stored in a stack like the Operand stack. Each name will use name length plus 3 bytes on the stack. Parser Local Names Stack to store local variable names - 1024 bytes. The local variable names for the function being compiled is stored in a stack like the Operand stack. Each name will use name length plus 3 bytes on the stack. Parser Goto Names Stack to store goto labels - 512 bytes. The goto label names for the function being compiled is stored in a stack like the Operand stack. Each name will use name length plus 3 bytes on the stack. Compiled Program and Data Size Program and Data size - 2048 bytes each. Each function is converted into an internal representation that has two parts, code and data. The code has the instructions, the data has constants and literal strings. These values are stored as strings in the mdat symbol table. Appendix B System Limits 87 APPENDIX C SYMBOL TABLE UTILITY - STU STU is a utility program that is used to manage symbol table files. Symbol table files use a b-tree structure. The b-tree files are balanced, i.e. the number of levels or depth of the tree to each key in the file at any given time is always the same. The first block of the file contains the top level node of the tree. The uppermost levels in the tree contain key and pointers to the lower level nodes. The leaf nodes contain the keys and the data associated with each key. When keys are stored in a node, repeated characters at the beginning of the key is not stored for each key. As keys are added in a random fashion, nodes are split as they become too large. The algorithm used attempts to keep each node at least half full, with the exception of the top level node. The stu fstat command can be used to see the efficiency of the storage. The stu pack command can be used to pack a key file into its most efficient storage use. The algorithm has specially written code to treat a new high key inserted into a key file. The algorithm currently used by Nadir to delete keys sets the value of the key to a null value. Using the stu pack command will also remove deleted keys. Command Line Syntax The Stmbol Table Utility Command Line has the following format stu <command> [switches] [file1 [file2]] The command may be:- Command Description bstat Print brief statistics for file1. check The internal structure of file1 is checked and reported on. copy The symbols in file1 are copied to a new file, file2. 88 Nadir Reference Manual dump Dumps the contents of each symbol or key in file1. fstat Print full statistics for file1. This requires a scan of the file. pack Packs file1. This is similar to copy, except output is to a temporary file. At the end of processing the original file is deleted, and the work file renamed to file1. rebuild Rebuilds file1. The program scans the file, picks any block that has a valid format, and inserts symbols in the block into a temporary file. At the end of processing the original file is deleted, and the work file renamed to file1. rtest Random Addition test. This creates file1, and randomly adds keys with random values. Used to test the software. The switches are:- Switch Description -p At end of program, pause and wait for a keystroke. -e Pause and wait at end of program only if the program errors. -c Pause and wait at end of program only on severe errors. -s Silent mode. The program will not produce any output. -n No progress reports. By default, stu shows the operation count as it performs its processing to give an indication of progress. Setting -n will turn off the progress reporting. -t Display time. Each line of output is preceded with the time. If a count of operations is shown, a rate of operations per second since the operation type was started is displayed in the format r=nnn. Appendix C Symbol Table Utility 89 -T<arg> Specify parameters for the rtest command. For more details see the section on rtest. -C<num> num specifies the number of keys to add when rtest is performed. STU Commands bstat - Brief Statistics The following shows example output using the bstat command. The bstat command shows statistics that can be easily and quickly obtained. Command stu bstat mdat.dat Output Brief File Statistics mdat.dat fileSize . . . . = 102400 blkSize . . . . . = 4096 depth . . . . . . = 2 fileSize is the size of the file in bytes. blkSize is the block size, the number of bytes in each node of the file. depth is the number of levels in the b-tree structure. The example file has 2 levels, the top most level, and the leaf node, which contains the symbol values. check - Check Integrity The check command can be used to check the structure of a symbol table. Command stu check mdat.dat Output Check Symbol Table mdat.dat 237 symbols found 237 symbols listed file structure correct The check command is performed in two phases. Firstly, each block is read and the contents checked. For each leaf node found, a count of symbols in the node is accumulated. This is the symbols found value. Secondly, the list function is performed, checking that each symbol name returned is after the previous in the collating sequence. This phase is exited if a symbol is found to be out of sequence. The count of the symbols is accumlated and is the symbols listed value. 90 Nadir Reference Manual If all nodes have a valid format and the symbols found agree with the symbols listed, the message "file structure correct" is displayed. The file in use flag will be reset if no errors are encountered. check messages The check command can output a number of informational messages. They are :- Message Text Comments file size not a multiple The first block of the of blocksize file contains the blocksize. There must be an integer number of blocks in the file. block not neatly filled The unused portion of a with nulls node must be filled with nulls. The block has been scanned correctly, but the data after the scan does not contain nulls symbol too large A block was scanned and an invalid symbol length was found. symbols not in order in During scanning a block block the symbol names were not in ascending collating sequence. block scan did not end Each block contains a on correct byte count of the bytes used in a block. The block scan completed, but not at the correct byte position. not a valid type byte Each block has a type byte, root block, index block, leaf block. An incorrect type byte was found. symbols found and listed The count of symbols don't match found by phase 1 and 2 are not equal. errors found Shown if any error condition was found file structure correct No errors have been found. The structure of the keyfile is correct. Appendix C Symbol Table Utility 91 copy - Copy Symbol Table The copy command can be used to copy the contents of one symbol file to another. The destination file is created. This is not a file copy. Each symbol in the source file is read and inserted into the destination file. The resulting file will have as much information possible in each of the nodes in the file. Command stu copy mdat.dat junk.dat Output Copy Symbol Table mdat.dat to junk.dat 237 symbols copied dump - Dump Symbol Table The dump command shows the contents of each of the symbol values in a hex style dump. Command stu dump mdat.dat Output Dump File mdat.dat (1) BlackOnWhite^c 0000 | 3a 01 00 00 03 16 00 00 00 07 03 30 00 00 00 07 |:..........0....| 0010 | 03 4b 00 00 00 07 03 64 00 00 00 07 03 78 00 00 |.K.....d.....x..| 0020 | 00 07 03 8e 00 00 00 07 03 9f 00 00 00 07 02 bc |................| 0030 | 00 02 c5 00 02 b5 00 0a 1e 03 07 01 01 |............. | (2) BlackOnWhite^d 0000 | 43 6f 6c 6f 75 72 41 72 65 61 42 6c 61 63 6b 4f |ColourAreaBlackO| ....file truncated.... fstat - Full Statistics The following shows example output using the fstat command. The fstat command shows more statistics that the bstat command. To compile the statistics, the file is scanned from the first symbol to the last. Command stu fstat mdat.dat 92 Nadir Reference Manual Output File Statistics mdat.dat fileSize . . . . = 102400 blkSize . . . . . = 4096 depth . . . . . . = 2 nameCnt . . . . . = 237 nameBytes . . . . = 3736 nameMin . . . . . = 6 nameMax . . . . . = 30 nameAvg . . . . . = 15 valueBytes . . . = 60797 valueMin . . . . = 1 valueMax . . . . = 1589 valueAvg . . . . = 256 nameCnt contains the number of symbols in the table. nameBytes is the total characters in all the names. This is the number of bytes used to store the internal representation of the symbol names. It does not include overhead. nameMin, nameAvg and nameMax are the minimum, average and maximum bytes used for the internal representation of the names. The text of the symbol name is not the same as the internal representation. valueBytes is the total characters in all the symbol values.. It does not include overhead. valueMin, valueAvg and valueMax are the minimum, average and maximum bytes used for the values. pack - Pack Symbol Table The pack command can be used to pack the contents of a file. This does the same processing as the copy command. The pack command will fit as much information as possible into each block of the file, and remove deleted symbol names. The source file, name.ext is copied to a file called name.$$$, using the stu copy algorithm. After the copy, name.bak is deleted, if it exists. The source name, name.ext is renamed to name.bak. The temporary file, name.$$$ is renamed to name.ext. Finally, name.bak is deleted. Command stu pack mdat.dat Output Pack Symbol Table mdat.dat 237 symbols copied Appendix C Symbol Table Utility 93 rbuild - Rebuild Symbol Table The rbuild command may be used to rebuild a file from a damaged file. The blocks of the file are read is the same manner as for the first phase of the check command. If the block is a leaf node, and passes all the block checks, the symbols in it are inserted into a temporary output file. After the rebuild, name.bak is deleted, if it exists. The source name, name.ext is renamed to name.bak. The temporary file, name.$$$ is renamed to name.ext. Finally, name.bak is deleted. Command stu rebuild mdat.dat Output Rebuild Symbol Table mdat.dat 237 symbols rebuilt rtest - Random Test The rtest command can be used to test the operation of the symbol insert functions. A number of switches may be used that control the type of names that are randomly generated and added to an existing file. The file can be checked at regular intervals. The rtest switches are described in the following table. rtest Description switch -Tc<num> A total count of num additions to the file will be attempted. Because the names of the symbols are generated randomly, some may fail because the name has been used already. Default value is 10000. -Tt<num> The file is checked (tested) after num additions. If not specified, num for -Tc is assumed. 94 Nadir Reference Manual -Tel<num> The lowest number of elements in the name. The number of elements is a random number between the low and high values inclusive. The type of element is chosen in order, the first string, second integer, third float, fourth date, fifth string and so on. Default value is 1. -Teh<num> The highest number of elements. Note that if -Tr is used, the name can have one more element. Default value is 4. -Trl<num> The low value for the number of repeats. The number of repeats is a random number between the low and high numbers. If non zero, then an extra element is added to the current name for the repeat number of times. Default value is 0. -Trh<num> The high value for the number of repeats. Default value is 0. -Tvl<num> The low value for the number of characters in the value for the randomly chosen name. The size of the value is a random value between the low and high values, inclusive. Default value is 1. -Tvh<num> The high value for the number of characters in the value. Default value is 50. If any of the high values are lower than the low values, the high value is set equal to the low value. Command stu rtest -Tc1000 junk.dat Output Random Test, file test.dat, add 1000, check every 1000 Name elements 1 - 4 Name repeats 0 - 0 Value length 1 - 50 1000 symbol adds attempted, 14 failed Check Symbol Table test.dat 986 symbols found 986 symbols listed file structure correct Appendix C Symbol Table Utility 95 APPENDIX D ERROR MESSAGES The error messages produced by Nadir use the same function internally as the Signal and Exit intrinsic functions. This appendix provides a list of the error messages and some extra description. The error messages contain a condition class. The errors are grouped by class. cnd - Condition Handler The condition handler provides a method for dealing with errors. When the Signal and Exit intrinsic functions are used, condition handler functions are called. The condition handler uses the setjmp and longjmp C functions, and uses a condition handler stack to save setjmp stack frames. Condition Stack Overflow A push of a new condition handler caused the condition handler stack to overflow. This can be caused by using the Process intrinsic function recursively. fm - File Manager The file manager is used to control the handles for text files. Each file opened with the FileOpen intrinsic function will use one of the file manager handles. All handles are open The limit for the number of open files has been reached. hm - Handle Manager The handle manager controls a system pool of handles. These include the FileOpen handles, and well as handles created in other modules of intrinsic functions such as Print Documents and Screen Dialogues. 96 Nadir Reference Manual All handles are used The limit for the number of system handles has been reached. key - Key File Functions The key functions are used to manipulate the b- tree structure that is used to implement the symbol table file. The key is the internal representation of a symbol name. Key and data too long <key> The sum of the length of the key and the length of the data has exceeded the maximum allowed. Key Stack Overflow Each level in the b-tree occupies one frame in the key stack. This error will occur when the maximum number of levels in a symbol table file has been exceeded. Key too long <key> The length of the key has exceeded the maximum allowed. Opening <name> block size incorrect (<filesize> != <size> * <cnt>) The file whose name is shown as name has been opened. The block size, size, and the block count, cnt have been extracted from the file header. When multiplied together, the file size should result. If not, this error will be shown. This will happen when files contain incorrect data. Opening <name> block size is <act>, not <spec> The file whose name is shown as name has been opened. The block size, act, has been extracted from the file header. This error occurs if the block size, spec, is specified in the SymOpen call, and it does not equal the actual size of the file. lex - Lexical Analysis Lexical Analysis breaks the input file into tokens. Examples of tokens are names, operators, integer and string constants. Appendix D Error Messages 97 Unterminated string This error occurs when the end of the Nadir input file is encountered before the closing character of a string literal or code string. mem - Memory Manager The memory manager performs all allocation and deallocation of memory. It can free all allocated memory when conditions are signalled and when the Nadir program is terminated. Out of Memory. Current <curr>, Maximum <max> A request for memory failed. The current amount of memory allocated in shown as curr, the maximum allocated at one time as max. Request size <size> too large A request was made for size bytes of memory and was too large. Under DOS, one allocation cannot be more than 64K, under Windows an allocation cannot exceed the memory block size, specified with the -Sm command line switch. mi - Macro Interpreter The macro interpreter is the module that interprets the output of the compilation of the macro source code. Compiled version <num>, execution version <num> The version of the Nadir program that was used to compile a function is different to that being used to execute it. The version is an internal number associated with the mi module, and is changed when the format of the compiled program is changed in a way that makes it not execute in the next version. i.e. The Nadir version may change, but the internal mi version number may remain unchanged. Stack overflow in <name> stack The size of the stack has been exhausted. name will refer to the type of stack. Possible values are described in the following table. 98 Nadir Reference Manual Stack Type Description Operand The values of function arguments and intermediate expression evaluation values for all functions currently being executed are stored in this stack. Local Value The values of local variables for all functions currently being executed are stored in this stack. Parm Value The values read from the parm symbol table when Nadir starts are stored in the parm value stack. Arg Name The names of arguments for the function being compiled are stored in this stack. Local Name The names of local variables for the function being compiled are stored in this stack. Label Name The names of labels in the function being compiled are stored in the label name stack. Program The constants and literals in the Data function being compiled are stored in the program data stack. mif - Macro Intrinsic Functions This module implements all the system intrinsic functions described in the Language Reference Manual. Browser not defined A text file was to be browsed by the user, but a browser program was not defined using the parm parameters. See gui^browser and text^browser in the Appendix A, System Parameters. Invalid symbol table <stid> The symbol table name, shown as stid is invalid. An valid name is univ or glob. This error occurs when an invalid name is passed to SymClose or SymLock. Appendix D Error Messages 99 mm - Macro Manager This module manages the reading and writing of all the data in the symbol table files. This includes the values of the compiled macros and symbol table values. A better name might be the symbol table manager. In any of the following error messages, stid will refer to the symbol table name, eg univ, and filename will be the filename of the symbol table file. errtext is error message text and is described in the vm section. Application cancelled at user's request The user does not want to wait any longer for a lock request. This error is shown after a user written lock query function has been executed and has returned with a true boolean value. Cannot create <filename>, <errtext> The filename is the name of a temporary symbol table file that could not be created when the Nadir program starts. Cannot open or create <filename>, <errtext> The filename is the name of a permanent symbol table file that could not be either opened or created when the Nadir program starts. Could not auto lock <stid>, <filename> A value was assigned to a symbol name. The symbol table had not been locked, and the system was attempting an automatic lock. This attempt failed. Could not lock <stid>, <filename> The system could not lock the symbol table. This error is shown if the user written function SysLockQuery does not exist. Invalid table in symbol <name> The first component of a symbol name, shown as name, is not the name of a valid symbol table. eg. It is not one of the system names or a user defined name. 100 Nadir Reference Manual Locking <stid>, <filename> for update, write not allowed An attempt has been made to lock a symbol table for update, but the user does not have write permission to the file. Macro Code not found <name> A function is to be executed and the macro code string could not be found in mdat or mlib. name is the name of the function. Macro Data not found <name> A function is to be executed and the macro data string could not be found. name is the name of the function. In this case the macro code string has been found. No ^ in symbol <name> A caret was not found in a symbol name. A caret must be present because the first component of the name is the symbol table name. No symbol table name on open or create A SymOpen or SymCreate function was called and the table name was empty. Open limit exceeded <stid> A SymOpen or SymCreate function was called, and the maximum allowable number of symbol table files were already opened. Symbol Table <stid>, <filename> not open A symbol was referenced, but the symbol table was not open. Symbol Table <stid>, <filename> not properly closed The symbol table was improperly closed, the single use command line switch was used, and there was no user written SysFileRecover function to perform. Test lock failed, <errtext> An attempt was made to lock a temporary file on startup to ensure that the DOS SHARE program has been loaded. SHARE had been loaded and the test lock failed for some other reason. Updating <stid>, <filename>, when locked for read A symbol value has been assigned in a symbol table that was locked by SymLock for read lock. Appendix D Error Messages 101 Updating <stid>, <filename>, write not allowed An attempt has been made to modify a symbol table, when the user does not have write permission to the file. When a symbol table is opened, Nadir checks whether the user has read/write access or read only access to the file. When the user has read only access, Nadir will continue, but will not allow symbol values to be modified. mp - Macro Parsing This module processes the Nadir input file. It performs the compilation of functions and produces the syntax error messages. Cannot process input with Runtime version This error occurs when the Runtime version of the program is used to process an input file. Invalid pre process flags <flags> One of the flags in a call to the PreProcessSet intrinsic function was not valid. Syntax Errors When a function is compiled with the Define keyword in the input file, many syntax errors may be produced. The message shown to the user is formatted in one of the following ways. In all cases msg refers to the text of the syntax error. <msg> at end of input This occurs when the syntax error occurs at the end of the input. <msg> at word <word> This is shown when a string is being processed. Strings can be processed using the Process intrinsic function. word is the current lexical token when the error occured. <msg> at word <word> on line <num>, <line> This is shown when the input file is being processed. word is the current lexical token when the error occured, num is the line number of the current line in the input file, and line the text of the current line. 102 Nadir Reference Manual Syntax Error Text Each of the syntax errors follow. break not in loop or switch A break statement was encountered but was not in a do, do while, for or switch statement. case not in switch A case statement was encountered but was not in a switch statement. continue not in loop A continue statement was encountered but was not in a do, do while or for statement. default not in switch A default statement was encountered that was not in a switch statement. Duplicate arg name One of the argument names in the argument name list after the Define keyword is duplicated. Expected ( The syntax of a statement expected a left parenthesis, but one was not seen. Expected ( or { The syntax of a statement expected a left parenthesis or left brace, but one was not seen. Expected ) The syntax of a statement expected a right parenthesis, but one was not seen. Expected ) or end of input This occurs when processing the Eval keyword. The end of input or a right parenthesis was not found after the Eval expression. Expected : The syntax of a statement expected a colon, but one was not seen. Expected ; The syntax of a statement expected a semicolon, but one was not seen. Appendix D Error Messages 103 Expected a compound statement The syntax after the Define keyword expects a compound statement, but one was not seen. Expected a label The syntax of a goto statement expected a label to be present, but one was not seen. Expected a statement The syntax of a statement expected a statement to be present, but one was not seen. Expected an expression The syntax of a statement expected an expression, but one was not seen. Expected Endif An Endif keyword was expected in the input file, but was not seen. This occurs at the end of the input file. Expected name after Define A function name was not found after the Define keyword in the input file. Expected ] The syntax of the statement expected a right bracket, but one was not seen. Expected ^ The syntax of the statement expected a caret, but one was not seen. Expected } The syntax of the statement expected a right brace, but one was not seen. Invalid arg list An invalid argument list was found. A valid argument list has a left parenthesis, none or more arguments separated by commas, ending with a right parenthesis. 104 Nadir Reference Manual Invalid arg name list The argument name list after the function name after the Define keyword was invalid. A valid argument list has a left parenthesis, none or more argument names separated by commas, ending with a right parenthesis. Invalid table name A macro name containing a caret was specified after the Define keyword. The name component before the first caret was an invalid symbol table name. Label <name> already defined The label, shown as name has already been defined in the current function. Label <name> not defined A label was referenced in a function, but was not defined. More than one default There was more than one default statement found in a switch statement. next arg not a symbol The argument of a next function is not a valid symbol name. No lvalue after & The reference operator was encountered, but was not followed by an lvalue. No matching If An Elseif, Else or Endif keyword was found in the input file without a matching If keyword. No subscript after argv The argv was not followed by a left bracket, an expression and a right bracket. No while after do The while reserved word of the do statement was not found. prev arg not a symbol The argument of a prev function is not a valid symbol name. Appendix D Error Messages 105 Subs expr too complex There were too many operands in a subscript expression. The complexity of the expression in a subscript is limited to a fairly generous size. Too much code The size of the code string exceeded the maximum allowable during the compilation of a function. The function has too much code and needs to be broken into smaller pieces. Too much data The size of the data string exceeded the maximum allowable during the compilation of a function. As with the code string, the function may have to be broken into smaller pieces. n - The main program This is the driver program that reads and parses the command line switches, and provides the main processing loop. Cannot find macro <name> A macro, with a name of name could not be found. This will the value of either the -a, -b or -e command line switch. Cannot open <name> A file, displayed as name, could not be opened. This can be the input file name, -i command line switch, the output file name, -o, or the library file name, -L, or -l. Cannot specify both -e and -p Only one of the command line switches -e and -p may be specified. -e will execute a macro, while -p is used to process a string. Single Use mode not available under Windows The -s command line option for single use mode, cannot be specified on the Windows version of Nadir. 106 Nadir Reference Manual st - Symbol Table The symbol table functions are used to convert a symbol name to and from the internal form used in the symbol table files. The module also has the function that is used to compare 2 names in their internal format. Element in symbol <name> too long One of the components in the symbol, shown as name is too long to represent the length in one character. Invalid key An internal representation was being converted to the symbol name, and an invalid component type was found. This occurs when a symbol table file is corrupt. Key for symbol <name> too long A symbol name, shown in name, was converted to the internal form. The result was longer than the maximum length. vm - Virtual Memory The vm module implements a buffering technique that is used by the module used to implement the symbol table files. This is the module that physically opens the symbol table files and performs the input and output to the files. Several of the errors include a name and error text. The name is the filename. It may the the right hand end of long file names. The text is the error text made using the errno from the C library routines. Error texts are :- Error text Remarks No such file or directory Too many open files Permission denied No such device File already exists Locking violation Appendix D Error Messages 107 errno = <num> If the error message is obscure or not likely to arise. num will be the value of errno when the failure occurred. Read error, file <name>, <text> An error occurred when performing a read from a symbol table file. Seek error, file <name>, <text> The error occurred when performing a seek, moving the file pointer in a symbol table file prior to a read or write. SHARE.EXE not loaded A region of a file was locked with the locking C library function. The return status indicated that the DOS program SHARE.EXE has not been loaded. This program has to be loaded before the locking functions will work. See the DOS SHARE command. Write error, file <name>, <text> An error occurred when writing a block to a symbol table file. Write error, file <name>, len != bufsize A write was performed, and the length returned was not equal to the amount requested. This will be the block size for the symbol table file. 108 Nadir Reference Manual INDEX Dump 55, 58 A E Addition operator + 43 argc 23, 40 Else 18, 83 Argument Elseif 18, 83 pass by reference 24, 40 Endif 18, 83 pass by value 23 Equality operators 44 argv 23, 38 Escape sequence 6 Assignment expression 45 Eval 17, 83 autoexec.bat 8 Exit 56, 96 Expansion rules 19 B Explode 56 Expression 34, 46 b-tree structure 85 evaluation 17 Boolean value 26 primary 37 Break statement 52 statement 49 Bunch 53 syntax 35 Expression evaluation 17 C F Case statement 51 Code string 6 FieldType 57 Collating sequence 28 FileClose 57 Command line 8 FileColumn 57 Comment 4, 19 FileDump 57 Compound statement 17, 47, 48 FileIndentSet 58 Condition Handler 96 FileLineGet 58 Conditional expression 45 FileOpen 57, 58, 84, 96 config.sys 8 FilePrint 59 Continue statement 52 FileRemove 60 Floating point number 7 D FloatToInt 60 For statement 51 Data directory 11 Function 22 Date format 82 arguments 22, 40 DateDay 53 call 39 DateDayName 53 return value 23 DateMonth 54 Function name 22, 39 DateMonthEnd 54 DateMonthName 54 G DateMonthStart 54 DateToday 55 Global symbol table 13 DateYear 55 Goto statement 52 Default statement 51 Default symbol tables 13 I Define 16, 22, 39, 47, 82, 83 Developer's Kit 1, 39, 53 If 18, 83 Division operator / 42 If statement 50 Do statement 50 Input file 4, 8, 9, 13, 14, DOS Share 8, 12, 108 20, 22, 47, 61, 63 DOS version 8, 66, 67, 76, 77, Integer 7 83 Intrinsic function 22 Index 109 K Parenthesis () 41 PreProcessSet 63 Keyword 4 prev operator 29, 41 redefining 16 Print 15, 60, 64 Process 65 L R Label statement 49 Level 60 Relational operators 43 Lexical analysis 20, 79, 97 Return statement 49 Lexical elements 4 Runtime version 8 LineCurr 20, 61, 62 LineGet 20, 61 S LineNum 63 Local value stack 12, 86 Signal 66, 74, 96 Local variable 12 Single user mode 12 Logical and operator && 44 Spawn 66 Logical negation operator ! 41 SpawnRestart 66 Logical operator 26 StrCat 67 Logical or operator || 45 StrFromAscii 67 Lvalue 38 StrFromLit 67, 72 StrFromQuoted 68 M String constant 6 Macro 22 literal 6 arguments 15 size 85 data symbol table 13 String concatenation operator . definition 16 43 library 10 StrLen 69 library symbol table 14 StrMatch 70 Macro data symbol table 11 StrPos 70 Macro name 16 StrSubs 71 Memory block 12 StrToAscii 71 Modulus operator % 42 StrToLit 68, 71 Multiplication operator * 42 StrToLower 72 StrToUpper 72 N Subscripting 27 function name 29 Name 4 symbol table name 29 next operator 29, 40 Subtraction operator - 43 Null statement 49 Switch statement 51 Null value 26 Symbol 13, 38 name 27, 84, 85 O table 27, 38, 84 value 85 Operand conversion rules 28, Symbol Table Utility 75, 88 31 SymClose 72, 74 Operand stack 12, 86 SymCreate 72 Operator 5 SymLock 73 precedence 35 SymLockQuery 74 Operators 34 SymOpen 72, 73, 74 Output file 8, 9, 55, 63, 64 SymRemove 75 OutputColumn 63 SysFileRecover 13 OutputIndentSet 63 System 76 SystemRestart 76 P SysType 77 Parameter symbol table 12, 14 Parameter value stack 86 110 Nadir Reference Manual T TaskNum 77 Temporary file directory 12 TimeNow 77 Token intrinsic functions 20 TokenNext 20, 77 TokenScanCreate 78 TokenScanDestroy 79 TokenTerm 79 TokenType 80 TokenValue 80 U Unary minus operator - 41 Unbunch 53, 80 Universal symbol table 12, 13 User written function 22 V Variable 26 date 25 float 25 integer 25 local 26 string 25 Variable types 24 W While statement 50 Whitespace 4, 14 Windows version 8, 12, 66, 76, 77, 83, 84 Index 111